SAP Graph Early Adopter Release, the free service plan is now available to all BTP customers and partners as well as indie developers under the SAP BTP free-tier service plan offering (subject to T&C) SAP Graph allows to create business data graphs wrapping access to backend data sources by leveraging OAuth2SAMLBearerAssertion destinations to SAP LOB Applications.

The brief is try to show how to unbox SAP Graph service without writing a single line of code against SAP SuccessFactors and SAP S/4HANA Cloud business applications. Pre-requisites: Access to SAP Graph product documentation. Access to SAP Graph API package on API Business Hub Access to SAP Graph Navigator. Access to SAP BTP free-tier global account. Access to SAP Graph Early Adopter Release free service plan in a sub-account of this global account. Alternatively, if SAP Graph Early Adopter Release service plan were not available to you, merely for testing purposes, SAP Graph beta service (if still available) could be considered. In order to access beta services, a BTP sub-account with beta features enabled is required. Please note that sub-accounts with beta features enabled may have different SLAs from productive sub-accounts, so generally speaking those beta features enabled sub-accounts should not be used in production. Access to at least one of the supported SAP LOB Application Optionally, access to SAP API Management, part of SAP Integration Suite Disclaimer: SAP Graph has been available in beta on SAP BTP platform for quite some time. If you were still considering trying out the beta version of this service, please note beta services are not meant for productive use and may be subject to changes or retired without notice. Please note all the code snippets below are provided “as is”. All the x509 certificates, bearer access and/or refresh tokens and the likes have been redacted. Images/data in this blog post is from SAP internal sandbox, sample data, or demo systems. Any resemblance to real data is purely coincidental. Access to some online resources referenced in this blog may be subject to a contractual relationship with SAP and a S-user login may be required.

Putting it all together

https://help.sap.com/viewer/product/SAP_GRAPH/PROD/en-US

https://www.npmjs.com/package/@sap/graph-toolkit

Where	What
SAP BTP Platform	Provision SAP Graph service instance in your BTP sub-account — see appendix for details Provision an instance of a destination service — see appendix for details Prepare destinations to SAP Applications. These destinations must be defined on the same BTP sub-account where the SAP Graph service instance has been provisioned — see appendix for details Optionally, manually clone and configure SAP Graph  ODatav4 API packages with SAP API Management
SAP Graph Key user local machine	Install the command line tool graphctl - see appendix for details Generate and Activate Business Data Graph Configuration File — see appendix for details.

 

Rehearsing your business graph with API Management

I have manually cloned and configured SAP Graph  ODatav4 API packages with SAP API Management.

As a result, all the implemented graph endpoints can be run securely in any internet facing frontend or backend application.

hcm	Bank
s4	SalesOrder

Conclusion

In a nutshell, in order to unbox SAP Graph, I only relied on the officially published SAP documentation and the Low-code/No-code tooling SAP BTP platform provides out-of-the-box.

Good to know:

• SAP API Management (APIM), which features built-in Discovery of SAP Business Hub published API packages, allowed me to cut down the SAP Graph adoption effort by at least eighty per cent (80%) or more.
• I also used APIM to rehearse the destinations towards business applications including the simulation of the graphctl auto-discovery.

Last but not least …

What is the value proposition of SAP Graph ?

• With the graph destinations auto-discovery it is fairly easy and convenient to implement graph API endpoints connected to the right business application
• By leveraging the API Management to implement the SAP Graph APIs, one does not even need to write a single line of code
• SAP Graph offers a homogenous access and data model across several business applications.
• Thus, developers, SIs, etc, instead of having to deal with each of the LOB APIs data formats separately, can focus more on tackling the business problem taking advantage of the unified ODATAv4 data model.

What are the main characteristics of SAP Graph ?

• Enterprise-grade security with password-less business users identity propagation with the 3-legged OAuth2 authorization code flow
• technical user access with OAuth2 client credentials authentication method.
• a unified data access to the following SAP LOB Applications: S/4HANA, S/4HANA Cloud, CX Sales Cloud, and SuccessFactors
• an ample documentation.

 

---

Troubleshooting

SuccessFactor ODATA API with sap.graph.Country and sap.graph.Currency entities

SAP SuccessFactors HXM Suite OData API: Developer Guide (V2) | PDF

2202759 – OData API call fails with an error: 400-COMDF_FILTER_ON_NOT_VISIBLE_PROPERTY

 

 

---

Appendix

SAP Graph service

Provision the SAP Graph service on a BTP sub-account as described in the Initial Setup in SAP BTP | SAP Help

WHAT	HOW
Add SAP Graph service entitlement to sub-account.
Goto service market place; locate the SAP Graph service and create a service instance from there as follows:
Step1. Make sure you are using the Other runtime environments to provision a service instance. Please use the free service plan if it is available to you; otherwise the beta service plan could be used for service discovery but please read carefully related comments in the Disclaimer section above.
Step2. Please add the following json formatted service parameters: { "oauth2-configuration": { "redirect-uris": [ "https://*/**", "http://*/**" ], "token-validity": 43200 }, "xsappname": "quovadis-sap-graph" }
Step3. The service creation will eventually kick off as depicted below: and then you can goto the service instance to continue with the service bindings configuration as follows:

Let’s create a service binding and download the service key to a quovadis-sap-graph.txt file on the SAP Graph key user local machine. This service key is required to log into graphctl command line tool.

Last but not least a role collection, namely SAP_Graph_Key_User role collection with the predefined SAP_Graph_Key_User role needs to be created on the SAP Graph service sub-account.

Please assign this newly created SAP_Graph_Key_User role collection to all BTP sub-account users who may need access to graphctl tool.

 

Destination service

Business destinations definitions

HCM – A generic SAP SuccessFactors destination definition.

Please refer to the following blog post, namely:

OAuth2SAMLBearerAssertion flow with SuccessFactors with Quovadis-SAP destination, for further details on how to configure a SF system with a BTP destination service

{
  "Name": "Quovadis-SAP",
  "Type": "HTTP",
  "URL": "https://<api url>/odata/v2",
  "Authentication": "OAuth2SAMLBearerAssertion",
  "ProxyType": "Internet",
  "KeyStorePassword": "<KeyStorePassword>",
  "tokenServiceURLType": "Dedicated",
  "audience": "www.successfactors.com",
  "companyId": "<companyId>",
  "Description": "Generic SFSF destination",
  "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession",
  "apiKey": "<apiKey>",
  "KeyStoreLocation": "quovadis-sap.pfx",
  "clientKey": "<clientKey>",
  "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "SystemUser": "<BizX user_id>",
  "tokenServiceURL": "https://<token url>/oauth/token"
}

S4 – A S/4HANA Cloud SaleOrder destination definition

Please refer to the following blog post, namely:

OAuth2SAMLBearerAssertion Flow with the SAP BTP Destination Service. S/4HANA Cloud, for further configuration details

{
  "Name": "QUOVADIS-ISVENG-JWT",
  "Type": "HTTP",
  "URL": "https://myXXXXXX.s4hana.ondemand.com/sap/opu/odata/sap/API_SALES_ORDER_SRV",
  "Authentication": "OAuth2SAMLBearerAssertion",
  "ProxyType": "Internet",
  "KeyStorePassword": "<KeyStorePassword>",
  "tokenServiceURLType": "Dedicated",
  "audience": "https://myXXXXXX.s4hana.ondemand.com",
  "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:x509",
  "Description": "API_SALES_ORDER_SRV",
  "tokenServiceUser": "<communication user>",
  "tokenServiceURL": "https://myXXXXXX-api.s4hana.ondemand.com/sap/bc/sec/oauth2/token",
  "tokenServicePassword": "<communication user password>",
  "clientKey": "<communication user>",
  "KeyStoreLocation": "quovadis_ateam-isveng.p12",
  "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "scope": "API_SALES_ORDER_SRV_0001",
  "userIdSource": "email"
}

Good to know:

• In either case please make sure the destination can fetch the ODATA service metadata by appending /$metadata to the URL property.
• This how graphctl will validate each destination during the graph discovery phase.

Graphctl

graphctl is a command line tool and requires Node.js version 14 with npm version 6 to run.

As I am using nvm, the node version manager, I need to first install the required version of nodejs and then tell nvm to use the version 14 as follows:

$ nvm install 14
Downloading and installing node v14.18.2...
Downloading https://nodejs.org/dist/v14.18.2/node-v14.18.2-darwin-x64.tar.gz...
################################################################################################################################################ 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v14.18.2 (npm v6.14.15)

$ nvm use 14
Now using node v14.18.2 (npm v6.14.15)

Now let us install graphctl:

$ npm install -g @sap/graph-toolkit
/Users/<userid>/.nvm/versions/node/v14.18.2/bin/graphctl -> /Users/<userid>/.nvm/versions/node/v14.18.2/lib/node_modules/@sap/graph-toolkit/lib/cli.js
+ @sap/graph-toolkit@3.0.3
added 204 packages from 149 contributors in 11.495s

and test the installation

$ graphctl --help
SAP Graph command line interface (v3.0.3)

Usage: graphctl <action> [object] [options] [params]

General actions:
login            Log in to configure a business data graph in your landscape
logout           Log out from your landscape.

Actions for config:
generate         Generate a graph configuration based on destinations in the BTP subaccount
activate         Activate a graph configuration to create a business data graph
list             List all activated graph configurations / business data graphs in the current landscape 
get              Retrieve a single graph configuration in the current landscape.             
delete           Delete a graph configuration and business data graph

General Options:
  -v, --version    Display the version number
  -h, --help       Display help on command

Tip:
Use 'graphctl <action> [object] --help' for command-specific help.

Example:
graphctl get config --help

c. login to sap graph with the credentials in the quovadis-sap-graph.txt

$ graphctl login -s quovadis-sap-graph.txt
Authorize uri: 
 https://theta.authentication.eu10.hana.ondemand.com/oauth/authorize?client_id=sb-d5384116-a446-4b33-91b5-8ad45258b8e6!b94272%7Csap-graph!b42725&response_type=code&redirect_uri=http://localhost:55223

As a result a bearer access token is retrieved and stored in a tokenData.json file in a hidden .graph directory as follows:

$ ls -ln ~/.graph/
total 24
-rw-r--r--@ 1 501  20  1206 xx Dec 15:27 serviceKey.json
-rw-r--r--@ 1 501  20  4911 xx Dec 15:27 tokenData.json

Good to know:

• The token is valid for 12 hours.

Business Data Graph

Please refer to Business Data Graph Configuration File | SAP Help

$ graphctl list config
✔ SAP Graph URL (enter to use default 'https://eu30.graph.sap'):  … 
This URL is now used as default.
Fetching Graph configurations from https://eu30.graph.sap
┌─────────┐
│ (index) │
├─────────┤
└─────────┘

 

Generate a default configuration file

All the SAP Graph sub-account level destinations will be scanned and tested against.

Good to know:

• However only the destinations that graph was able to validate will be taken into account.

$ graphctl generate config --help
SAP Graph command line interface (v3.0.3)

Usage: graphctl generate config|c [options]

Generate a graph configuration based on destinations in the BTP subaccount

Options:
  -f, --file <graphConfiguration>  Write graph configuration to a file
  -h, --help                       Display help on command

Example:
  graphctl generate config -f ./graph-configuration-v1.json

 

$ graphctl generate config -f ./graph-configuration-v1.json
Fetching Graph configuration from https://eu30.graph.sap
Graph Configuration Template generation was successfully started

 Waiting for graph configuration template to be generated 
 checking template generation status on https://eu30.graph.sap/config/v1/sap.graph/GraphConfigurationTemplate 
 (You can use CTRL + C to exit, this will not stop the generation of the graph configuration)

...

Graph config file has been created at: ./graph-configuration-v1.json

Data sources

Data sources are created automatically during the configuration generation process through auto-discovery of the LOB destination definitions. The tool will  take its best guess and decide automatically on the sap.graph entity affinity assignment (like sap.graph.Bank with sap.hcm). However this can be changed manually if required.

$ cat ./graph-configuration-v1.json
{
  "businessDataGraphIdentifier": "v1",
  "graphModelVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "dataSources": [
    {
      "name": "s4",
      "services": [
        {
          "destinationName": "QUOVADIS-ISVENG"
        },
        {
          "destinationName": "QUOVADIS-ISVENG-JWT"
        }
      ]
    },
    {
      "name": "hcm",
      "services": [
        {
          "destinationName": "Quovadis-SAP"
        }
      ]
    }
  ],
  "locatingPolicy": {
    "cues": [],
    "rules": [
      {
        "name": "sap.s4.*",
        "leading": "s4",
        "local": []
      },
      {
        "name": "sap.hcm.*",
        "leading": "hcm",
        "local": []
      },
      {
        "name": "sap.graph.*",
        "leading": "s4",
        "local": ["hcm"]
      },
      {
        "name": "sap.graph.Bank",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.Company",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.CostCenter",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.Country",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.Currency",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.Job",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.Language",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.PersonMaritalStatus",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.PersonTitle",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.TimeSheet",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.WorkAssignment",
        "leading": "hcm"
      },
      {
        "name": "sap.graph.WorkforcePerson",
        "leading": "hcm"
      }
    ]
  }
}

Update and activate the graph configuration

In case there is an existing configuration in the graph list, in order to update it, you may need to delete it first as follows:

$ graphctl delete config v1
Fetching Graph configuration from https://eu30.graph.sap
✔ Do you want to delete the graph configuration with v1? … yes
Deleting graph configuration from https://eu30.graph.sap
Graph configuration with business data graph identifier v1 has been deleted.

Then proceed to update and activate a new graph configuration:

$ graphctl activate config -f ./graph-configuration-v1.json
Updating Graph Configuration on https://eu30.graph.sap
Graph Configuration was successfully uploaded

 Waiting for graph configuration to be processed 
 checking status on https://eu30.graph.sap/config/v1/sap.graph/GraphConfiguration/v1 
 (You can use CTRL + C to exit, this will not stop the processing of the graph configuration)

...
Graph configuration passed validations and deployment has started. 
Deployment will be available at https://eu30.graph.sap/api/v1/metadata/entities 
[
  {
    "message": "Entity API_SALES_ORDER_SRV.A_SalesOrder is provided by several destinations of business system s4 : QUOVADIS-ISVENG, apiVersion: 1; QUOVADIS-ISVENG-JWT, apiVersion: 1. The entity will be served by destination: QUOVADIS-ISVENG",
    "location": null,
    "level": "WARNING"
  },
  {
    "level": "WARNING",
    "location": "<location-guid>/translations/PersonMaritalStatus.hcm.jsonc",
    "message": "attribute 'id': target: implicit type conversion: expected cds.Integer64, found cds.String"
  },

]

Eventually you may list available configurations:

$ graphctl list config
Fetching Graph configurations from https://eu30.graph.sap
┌─────────┬─────────────────────────────┬───────────────────┬─────────────┐
│ (index) │ businessDataGraphIdentifier │ graphModelVersion │   status    │
├─────────┼─────────────────────────────┼───────────────────┼─────────────┤
│    0    │            'v1'             │      '1.0.0'      │ 'AVAILABLE' │
└─────────┴─────────────────────────────┴───────────────────┴─────────────┘