 |
 | 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:
Disclaimer:
|
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 |
|
| SAP Graph Key user local machine |
|
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: |  |
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.495sand 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-...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.jsonGood 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.jsonData 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' │
└─────────┴─────────────────────────────┴───────────────────┴─────────────┘
- SAP Managed Tags:
2 Comments
