Skip to Content

GeoJSON is standard format for describing geographical features such as countries, counties and arbitrary external feature collections. It is based on JavaScript Object Notation (JSON). The Visual Business Content Database provides infrastructure for uploading and maintaining GeoJSON content pertaining to various geographic features and facilitates its retrieval in order to be used in the context of sap.ui.vbm.GeoMap or sap.ui.vbm.AnalyticMap.

BACKGROUND

Prior to the implementation of the Visual Business Content Database, the GeoJSON was uploaded to and served from the MIME repository. It was limited in that it could only support country data (L0) and had to be mandatorily uploaded to a specified location. Also, the file also had to be named L0.json.

There exist a few blogs on SCN which explain this approach in detail. However, with the implementation of the Visual Business Content Database, this approach, along with some of the steps outlined in the blog, becomes obsolete. It is recommended to follow the steps described here in their entirety to set up the Visual Business Choropleth Map from scratch.

OVERVIEW

The Visual Business Content Database is set of database tables in the ABAP backend that contain the GeoJSON content.

The primary step involved in setting up Visual Business Choropleth Map with content being served from the Visual Business Content Database(backend) is the upload of the GeoJSON content.

Once the content has been uploaded,the map control (sap.ui.vbm.GeoMap or sap.ui.vbm.AnalyticMap) needs to be configured to retrieve content from the Visual Business Content Database.

UPLOAD OF GEOJSON CONTENT

The process of upload of GeoJSON content to the Visual Business Content Database can be seen a sequence of three broad steps.

The first is identifying the source of data. The geographical features that eventually need to be displayed on the map vary vastly – ranging from something as standard as countries of the world to something extremely custom such as sales areas, etc. In line with that, there are variety of sources that provide this content with varying level of detail.

Once the appropriate content has been agreed upon, the same may need to be transformed into GeoJSON format appropriate for it to be uploaded to the content database. This step isn’t needed of the source identified in the previous step already provides GeoJSON data.

Lastly, the GeoJSON content needs to be uploaded to the Visual Business Content Database. This is done using either SAP GUI transactions or SAP NetWeaver Gateway OData service.

FETCHING AND TRANSFORMING CONTENT GEOJSON

The content GeoJSON can be of three types – depending upon the distinct nature of geographical feature, each is expected to represent.

  • Countries (L0-data)
  • Counties (L1-data)
  • ExternalFeatureCollections

L0 and L1 Content Data Sources – Natural Earth

One such source of L0 & L1 content is Natural Earth (www.naturalearthdata.com). Follow the steps below to download the content from it and transform it so that the resulting GeoJSON can be used during the upload process. Refer to Natural Earth’s terms of use and details about the accuracy of boundary data.

  • Navigate to naturalearthdata.com/downloads/. Data in various themes and in varying levels of detail is available in there – with 1:10m being the most detail.

Choose the “Cultural” theme.

L0 data is referred to as “Admin 0 – Countries”. L1 data is referred to as “Admin 1 – States, Provinces”.

For L0-data, 1:10m to 1:110m provide the same content data for countries in varying level of detail. For L1-data, 1:10m and 1:110m differ in terms that 1:110m provides content data for counties of just the US while 1:10m provides content data for counties for all the countries.

  • Depending upon the need for level of detail and the type of data to be displayed, download the appropriate content.

Further steps refer to L0 data from 1:10m as an example. However, they should be identical for a different type of data or a different level of detail. Click on the button “Download Countries” under the section “Admin 0 – Countries” on https://www.naturalearthdata.com/downloads/10m-cultural-vectors/. This will download ne_10m_admin_0_countries.zip.

Choose the level of detail as appropriate – for the greater the level of detail, the greater the size of the content data to be upload into the Visual Business Content Database, and eventually greater the amount of data to be retrieved when used with sap.ui.vbm.GeoMap or sap.ui.vbm.AnalyticMap.

  • Extract the contents of the zip file to some location on the disk.
  • The extracted archive has a file named “ne_10m_admin_0_countries.shp” – that contains the content data for boundaries of countries of the world in ESRI shape file format. This needs to be transformed into GeoJSON in order to be able to upload into the Visual Business Content Database. This is done using Geospatial Data Abstraction Library (GDAL- www.gdal.org). Navigate to http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries to download the operating system specific binaries. Further steps refer to GISInternals.
  • Choose Windows – GISInternals. Alternatively, navigate to http://www.gisinternals.com/release.php and choose the appropriate download depending upon the compiler architecture.
  • Download the “Generic installer for the GDAL core components” (*-core.msi).
  • Install it. The “Typical” installation is sufficient in this case. If the installation location isn’t changed, this would typically install GDAL at “C:\Program Files\GDAL”.
    At the above installation location, there must exist ogr2ogr.exe. This will be used to convert the ESRI shape files downloaded from Natural Earth. Copy the path to this executable.
  • Open Command Prompt and navigate extracted archive from Natural Earth.
  • Run “GDALShell.bat” from the installation folder of GDAL.
  • The usage of ogr2ogr2.exe in our case as below.
<path to ogr2ogr.exe> -f “GeoJSON” <path to output GeoJSON> <path to ESRI .shp file>​
  • In this case, it should be as below. The output GeoJSON file is named Geo.json.
“C:\Program Files\GDAL\ogr2ogr.exe” -f  “GeoJSON” “Geo.json” “ne_10m_admin_0_countries.shp”

If the location of the output GeoJSON is chosen to be inside the installation directory in Program Files – as shown in the previous blog explaining upload of content to the MIME repository, the Command Prompt needs to be run as Administrator.

Also, the previous approach of uploading the content to the MIME repository required running of a couple of ABAP reports to add ISO codes. These are no longer needed when uploading to Visual Business Content Database.

  • The output L0/L1 content GeoJSON obtained from above is now ready to be uploaded to Visual Business Content Database.

External Feature Collections

One possible option for obtaining the GeoJSON pertaining to arbitrary geographical shapes is using www.geojson.io. It provides an interactive way to draw geographical features – such as sales areas on a map and then producing its resulting content GeoJSON. This is to be saved to the disk and used later during the upload to Visual Business Content Database.

UPLOAD TO VISUAL BUSINESS CONTENT DATABASE 

Once the content GeoJSON has been prepared, it can be uploaded to the Visual Business Content Database using one of the below.

  • ABAP Transactions
  • NetWeaver Gateway OData Service

The NetWeaver Gateway OData Service is alternative for situations where it’s not possible to run ABAP transaction using SAP GUI.  Using this also requires building a client application with some user interface that would in turn invoke the service.

Authorizations

The upload of GeoJSON content is protected by ABAP authorization concept. It is seen as an administrative task – that should be protected by appropriate authority checks. The user which is used to perform the upload needs to possess these authorizations in order to be able to upload. This is irrespective of the approach used to perform the upload – ABAP transactions or service.

The primary authorization object used is S_TABU_NAM with the below authorization field-values.

S_TABU_NAM Field Value
ACTVT ‘02’
TABLE VBI_FCOL_DEFAULT

Additionally, uploading using the ABAP transactions will require S_TCODE with appropriate field-values assigned while using the service will need S_SERVICE with appropriate field-values assigned to the user.

The SU22 defaults for the ABAP transactions and TADIR Service (IWSV) have been appropriately maintained and hence assigning them to the user’s menu in profile generator (PFCG) would propose most of these values as defaults. Post this, generation of the authorization profile and assigning it to the user should grant the user with the required authorizations.

ABAP Transactions

There are three transactions to upload the content GeoJSON depending upon the type of content being uploaded.

Transaction Code Type of Content
VBI_UPLOAD_L0 Countries
VBI_UPLOAD_L1 Counties
VBI_UPLOAD_FC External Feature Collections

Each of these transactions takes a Feature Collection Key input – that is used to identify the content at the time of retrieval. For all the required inputs – Feature Collection Key, Version, Default Version, Scale of the feature objects, Description, default values are proposed which may be accepted.

For the transactions VBI_UPLOAD_L0 and VBI_UPLOAD_L1, the value for Feature Collection Key mandatorily needs to be L0-ADMIN and L1-ADMIN respectively. This is case sensitive. This is required technically to be able to maintain relationship between L0 and L1 [countries and counties in them] and during retrieval.

For older releases of SAP_UI, there was a case mismatch with the above in the proposed default values of Feature Collection Key for the transactions VBI_UPLOAD_L0 and VBI_UPLOAD_L1. This has now been corrected.

It is required for L0 data to be uploaded prior to the uploading of L1 data. This is needed to relate the L1 data (counties) with L0 data(countries).

Upon execution, the file containing the GeoJSON needs to be selected from the file picker and subsequent prompt regarding content update need to be confirmed.

NetWeaver Gateway OData Service

In more recent releases of SAP_UI, an OData service has been delivered in order facilitate the upload of GeoJSON content to the Visual Business Content Database. Similar to transactions, the service allows for upload of L0-data, L1-data and external feature collections.

The external name of the service is VBI_CONTENT_UPLOAD_SERVICE. The entity data model for the service is simple with only three allowed distinct entity sets – Countries, Counties and FeatureCollections. On these entity sets, only HTTP POST operation is allowed – in line with the idea that this is meant to be a content upload service only. The JSON escaped GeoJSON content along with the other parameters required to perform the content upload are expected to be part of the HTTP request body.

Service Activation

As with any other gateway service, the content upload service needs to be activated using the transaction /IWFND/MAINT_SERVICE in the system that is appropriate according to prevalent gateway deployment scenario. The external service name to be used while searching for activation should be VBI_CONTENT_UPLOAD_SERVICE.

As an outcome of this, a HTTP GET performed like the below should return the service document with the HTTP status code of 200. This is a pre-requisite for the subsequent steps.

https://<system>:<port>/sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV?sap-client=<client>

A simple way to test this would be to post the above URL into a browser and observe that the service document is returned. A HTTP status of 40* with an appropriate error message for the above indicates that the service has not been successfully activated.

User Interface for Content Upload

The Visual Business Content Database provides merely a service to enable the upload. However, to be able to perform the upload interactively, an application with a user interface is needed. This user interface can be as trivial as a webpage with an input-text field to paste the content data and a button to trigger the upload. The application logic (JavaScript code in case of aHTML/JavaScript web page) would involve invoking the service with the provided inputs.

It is likely to encounter issues with cross origin requests if the service and the webpage are hosted on different servers – given most browsers tend to block them.f the application has been developed using HTML/JavaScript and the server on which the service is hosted is above certain release-SP of NetWeaver, the web page can be uploaded to the same server as the service is hosted on, using “Eclipse – SAPUI5 ABAP Repository Team Provider”. This will rule out issues with CORS entirely.

The remaining steps outlined assume that the upload application is written in JavaScript and the code snippets provided will be in line with it.

A REST client such as POSTMAN for Google Chrome normally would have been sufficient for this, but for the handing of CSRF token described next.

Handling CSRF Token

Modifying requests such as HTTP POST are protected by SAP NetWeaver Gateway against Cross Site Request Forgery (CSRF) attacks. Normally this requires the client to provide a CSRF token along with the modifying request. The client can obtain this token with the first non-modifying call to the service by setting the HTTP header “X-CSRF-Token” to the value “Fetch”. A CSRF token is returned by the server in the same response header. The client can then use it for modifying requests using header “X-CSRF-Token”.

Since the content upload service supports HTTP POST only, the only non-modifying request that can be used to obtain the CSRF token is HTTP HEAD as shown in the below snippet.

var xhrForHead = new XMLHttpRequest()
var csrfToken

xhrForHead.onreadystatechange = () => {
    if (xhrForHead.readyState == 4) {
        csrfToken = xhrForHead.getResponseHeader("X-CSRF-Token")
    }
};

xhrForHead.open(
    "HEAD", 
    "../../../../../sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV?sap-client=<sap-client>",
    true)
    
xhrForHead.setRequestHeader("Content-Type", "application/json")
xhrForHead.setRequestHeader("X-CSRF-Token", "fetch")
xhrForHead.send()

Service Invocation

As described in earlier sections the service enables upload of L0-data (Countries), L1-data (Counties) and Feature Collections. The below indicate the HTTP POST URLs that need to be used.

Type URL
Countries https://<system>:<port>/sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/Countries?sap-client=<client>
Counties https://<system>:<port>/sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/Counties?sap-client=<client>
FCs https://<system>:<port>/sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/FeatureCollections?sap-client=<client>

The following snippet indicates the invocation of the service for the case of Feature Collections. It would be similar for Countries and Counties except for the obvious difference in their request URLs.

It should be placed in some sort of event handler – click of button that triggers the upload process. It assumes the presence of HTML input fields with specific Ids used with jQuery as below and retrieves values entered in them.

var upload = (contentCategory, reqBody) => {
    var reqHdr = {
        method          : "POST",
        queryStr        : () => "sap-client=<sap-client>&sap-language=EN"
    }

    switch (contentCategory) {
        case "Countries":
            reqHdr.requestUri = () => "../../../../../sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/Countries"
            break
        case "Counties":
            reqHdr.requestUri = () => "../../../../../sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/Counties"
            break
        case "FeatureCollection":
            reqHdr.requestUri = () => "../../../../../sap/opu/odata/sap/VBI_CONTENT_UPLOAD_SRV/FeatureCollections"
            break
    }

    var xhr = new XMLHttpRequest()
    xhr.onreadystatechange = () => {
        if (xhr.readyState == 4) {
            console.log(JSON.stringify(xhr.response))
        }
    }

    xhr.open(reqHdr.method, reqHdr.requestUri() + "?" + reqHdr.queryStr(), true)
    xhr.setRequestHeader("Content-Type", "application/json")
    xhr.setRequestHeader("Accept", "application/json")
    xhr.setRequestHeader("X-CSRF-Token", csrfToken)
    xhr.send(reqBody)
}

var reqBody = {
    ContentKey: $("#contentkey").val(),
    Version: $("#version").val(),
    Default: $("#default").val() === "on",
    Scale: $("#scale").val(),
    Description: $("#description").val(),
    ContentString: $("#content").val()
}
upload("FeatureCollection", JSON.stringify(reqBody))

This would result in the content being uploaded to the Visual Business Content Database.

The value for csrfToken is what was previously obtained out of performing a HTTP GET.

The Content GeoJSON is set on ContentString attribute of HTTP request body as a string and then JSON escaped.

For uploading countries and counties, the ContentKey attribute in the HTTP request body must have a value L0-ADMIN and L1-ADMIN respectively. This is case sensitive. This is required technically to be able to maintain relationship between L0 and L1 [countries and counties in them] and during retrieval.

It is required for L0 data to be uploaded prior to the uploading of L1 data. This is needed to relate the L1 data (counties) with L1 data(countries).

Upload Response

Normally a HTTP POST is expected to return the created entity back in the HTTP response. However, given the enormous size that the GeoJSON content can be of – depending upon the level of detail and the nature of data, it isn’t practical to return the content GeoJSON string. The response body contains all other parameters that were passed at the time of triggering the HTTP POST.

The only meaningful values to be parsed out of the response is the HTTP status code. For a successful upload, a status code of 201 is returned. This along with all other response codes returned are standard response codes returned out of SAP NetWeaver Gateway and they imply their usual outcomes.

The only custom handling in the service implementation is for the failure for an authority check. As was the case with usage of ABAP transactions, in addition to the standard authority checks – such as the ones of external service invocation (S_SERVICE), an additional check is performed for the authorization object S_TABU_NAM with the below authorization field-values.

S_TABU_NAM Field Value
ACTVT ‘02’
TABLE VBI_FCOL_DEFAULT

If the authority check fails, a HTTP status of 400 is returned with the response body as below.

{
    "error": {
        "code": "/IWBEP/CM_MGW_RT/000",
        "message": {
            "lang": "en",
            "value": "User does not have the sufficient authorizations."
        },
        "innererror": {
            "transactionid": "----------------",
            "timestamp": "----------------",
            "Error_Resolution": {
                "SAP_Transaction": "Run transaction /IWFND/ERROR_LOG on SAP NW Gateway 
hub system and search for entries with the timestamp above for more details",
                "SAP_Note": "See SAP Note 1797736 for error analysis (https://service.sap.com/sap/support/notes/1797736)"
            },
            "errordetails": [
                {
                    "code": "/IWBEP/CX_MGW_BUSI_EXCEPTION",
                    "message": "User does not have the sufficient authorizations",
                    "propertyref": "",
                    "severity": "error",
                    "target": ""
                }
            ]
        }
    }
}

RETRIEVAL OF GEOJSON CONTENT

The GeoJSON content is uploaded to the Visual Business Content Database using either the ABAP transactions or the SAP NetWeaver Gateway OData service.

This GeoJSON content can be retrieved using a REST service and GeoJSON content thus obtained can be used to draw the respective geographical features they represent.

In SAPUI5, this can be done using sap.ui.vbm.AnalyticMap or sap.ui.vbm.GeoMap. The subsequent sections are based of SAPUI5 and JavaScript.

BORDERS ON ANALYTIC MAP

The sap.ui.vbm.AnalyticMap is a SAPUI5 control which allows boundaries in the map to be drawn according to GeoJSON content. It does not have a base map layer. It needs to be provided with a source of content GeoJSON. This is done by assigning the GeoJSON content source’s URL to the static property sap.ui.vbm.AnalyticMap.GeoJSONURL before the control’s instantiation.

This URL can point to the server on which the Visual Business Content Database is hosted which would result in geographic boundaries on the map control being drawn based on the content retrieved from the Visual Business Content Database.

sap.ui.vbm.AnalyticMap.GeoJSONURL = 
    "https://<system>:<port>/vbi/analyticmap/L0.json?sap-client=<client>"
const oMap = new AnalyticMap()

GEOJSON LAYER ON GEOMAP

The sap.ui.vbm.GeoMap is a comprehensive SAPUI5 control which enables viewing business data in a geographical context. One of inputs it need to be provided with is a collection of map layer stacks which are displayed as base map tiles in the control. Visual Object are then rendered above it as overlays thereby providing the whole thing a geographical context.

The GeoMap control has an aggregation geoJsonLayers that can be set to GeoJSON retrieved from Visual Business Content Database. This would result in the geographical features represented by the GeoJSON being drawn over a base map layer in the GeoMap control as below.

In this illustration, the L1-data (counties/provinces) of Germany was fetched from the Visual Business Content Database using the Analytic Map REST service and then displayed as regions over the base map tiles. The snippet below shows how this was achieved.

const oMap = new sap.ui.vbm.GeoMap({
    width: "100%",
    height: "100%"
})
oMap.setMapConfiguration(config)

oMap.addGeoJsonLayer(new sap.ui.vbm.GeoJsonLayer({
    srcURL: "https://<server>:<port>/sap/bc/vbi/analyticmap/L1.json?sap-client=<client>&country=DE",
    defaultFillColor: "rgba(0, 0, 0, 0)",
    defaultBorderColor: "rgba(255, 0, 0, 1)",
    defaultLineWidth: 10
}))

ANALYTIC MAP SERVICE

The analytic map service is a REST service that provides a mechanism for retrieval for GeoJSON from Visual Business Content Database. As shown in preceding sections, the URL to this service can set to SAPUI5 control properties in order to display the geographical features represented by the GeoJSON on the map control.

As with the upload of content GeoJSON, there are three different types of content that can be retrieved – L0-data (Countries), L1-data (Counties) and External Feature Collections.

Retrieval of L0-data

The L0-data (Country boundaries) are retrieved from the Visual Business Content Database by performing a HTTP GET from the below URL. The response, if successful, will contain the content GeoJSON representing the boundaries of the countries of the world (as uploaded from Natural Earth in this case).

https://<server>:<port>/sap/bc/vbi/analyticmap/L0.json?sap-client=<client>

The following illustrates an Analytic Map control with country boundaries drawn based on the GeoJSON retrieved from Visual Business Content Database.

Retrieval of L1-data

The Analytic Map allows for retrieval of L1 data. In addition to indicating the type of content to be retrieved as L1, an additional parameter as a filter condition (ex. Country for which Counties are to be retrieved) needs to be specified.

L1-data for restricted by Countries

This is easiest of L1 retrievals. It allows for retrieval of county data for one or more countries by specifying a parameter to that effect. The below indicates a sample URL to retrieve L1 content for Kingdom of Saudi Arabia and Brazil.

https://<server>:<port>/sap/bc/vbi/analyticmap/L1.json?sap-client=<client>&country=SA,BR

The following shows the result of a GeoJSON layer added to GeoMap control out of the content retrieved from the above URL.

L1-data by Counties

It is also possible to restrict the L1-data by specifying one more county codes. The below retrieves the content for states of Montana and Texas in the United States.

https://<server>:<port>/sap/bc/vbi/analyticmap/L1.json?sap-client=111&county=US-TX,US-MT

The below is outcome of the resulting content added to GeoMap as GeoJSON layer.

L1-data by Viewport and Selection Mode

It is also possible to restrict the L1-data between a maximum and a minimum bound of geo-coordinates. The bounds are specified using the option viewport. An option to specify a one of the selection modes – to further restrict the L1 data is also available. The following sections illustrate the differences between the various selection modes with the same viewport. The viewport is a rectangle colored in yellow and is placed somewhere over Australia and New Zealand.

Selection Mode -visible

The URL for this option is as below.

https://<server>:<port>/sap/bc /vbi/analyticmap/L1.json?
sap-client=111&
viewport=[[137.197265625;-53.12040528310657;0],[206.630859375;-31.728167146023935;0]]
&selection=visible

The resulting L1-data of this on GeoMap control is as below with boundaries in red. Note that the states of New South Wales and South Australia are returned as part of the content GeoJSON from the service and hence marked with red boundaries even though they aren’t completely inside the bounds of the viewport specified (yellow).

Selection Mode -inside

The URL for this option is as below.

https://<server>:<port>/sap/bc /vbi/analyticmap/L1.json?
sap-client=111&
viewport=[[137.197265625;-53.12040528310657;0],[206.630859375;-31.728167146023935;0]]
&selection=inside

The resulting L1-data of this on GeoMap control is as below with boundaries in red. Note that the states of New South Wales and South Australia are not returned as part of the content GeoJSON and hence not marked with red boundaries since they aren’t completely inside the bounds of the viewport specified (yellow). The states of Victoria and Tasmania however – which lies completely inside the bounds of the viewport are marked appropriately.

Selection Mode – center-country

The URL for this option is as below.

https://<server>:<port>/sap/bc /vbi/analyticmap/L1.json?
sap-client=111&
viewport=[[137.197265625;-53.12040528310657;0],[206.630859375;-31.728167146023935;0]]
&selection=center-country

The resulting L1-data of this on GeoMap control is as below – with boundaries in red. The country at the center of the viewport is New Zealand and hence only it’s state boundaries are marked in red. None of the states of the Australia were fetched as part of the resulting content data.

Retrieval of Feature Collections

Feature Collections are identified for retrieval using their unique content key used at the time of upload. The URL is as shown below.

https://<server>:<port>/sap/bc/vbi/analyticmap/FC(<Key>).json?sap-client=<client>

The below shows the result for an arbitrary feature collection uploaded to the Visual Business Content Database and then retrieved using the Analytic Map REST service referring to the same key used at the time of upload.

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply