ABAP SDK for IBM watsonx, using SAP NetWeaver
ABAP® client library to use the [watsonx.ai Runtime][wml] (formerly
Watson Machine Learning) and the [watsonx.ai][wxai] APIs.
This is a community SDK written by ABAPers for the ABAPers in the Open
Source community, to provide easy usage of IBM®
watsonx™ services in innovation initiatives combined with
any SAP® application which is run on SAP
NetWeaver® 7.50 and above, such as SAP Business Suite or
SAP S/4HANA® on-premises edition. It is the choice and
responsibility of application developers how this community SDK is
used.
Additionally, as the ABAP SDK is a community release it is not updated
with the same schedule as IBM-supported SDKs. Please see more
information in Support and Feedback.
Choose ABAP SDK release for the applicable ABAP Runtime
| abap-sdk-nwas-x | abap-sdk-btp-x |
|---|
| for SAP NetWeaver® AS ABAP 7.50+ | for SAP BTP ABAP Environment |
| tested on SAP Business Suite and SAP S/4HANA on-premises edition | tested with SAP BTP ABAP Environment 2405 |
this repository | |
Table of Contents
Announcements
Version 1.5.0 released
Version v1.5.0 of the SDK has been released - see what's changed in
the migration guide.
Before you begin
- You need an [IBM Cloud][ibm_cloud_onboarding] account.
Installation
The client library is provided as abapGit repository. Proceed as
follows to clone the ABAP SDK code to your SAP system.
- Install [abapGit][abapgit], using the [abapGit Docs][abapgit_docs]
- Use abapGit to clone the ABAP SDK Git repository into your SAP
system.
- Assign the ABAP SDK to the package
ZIBMX when performing setup of
the abapGit repository.
SAP System Configuration
SAP Profile Parameters
The following SAP profile parameter settings are recommended.
icm/HTTPS/client_sni_enabled = TRUE
ssl/ciphersuites = 135:PFS:HIGH::EC_P256:EC_HIGH
ssl/client_ciphersuites = 150:PFS:HIGH::EC_P256:EC_HIGH
Proxy configuration
The client library respects the ABAP proxy settings. If you are using
a central proxy server that is not already configured in your SAP
system, proceed as follows.
- Logon to the SAP system and call transaction SICF.
- Click Execute (or press F8).
- Select menu item Client → Proxy Settings.
- On tab Global Settings: Select Proxy Setting is Active and No
Proxy Setting for Local Server.
- On tabs HTTP Protocol and HTTPS Protocol specify the proxy
Host Name and Port. If the proxy server requires logon
credentials, also specify User Name and Password.
- Click Execute (F8) and OK.
SSL Certificates
Communication between SAP and the IBM Cloud is secured by the
Transport Layer Security (TLS) protocol, also known as Secure Sockets
Layer (SSL). SSL requires certificates that must be stored on the SAP
application server in the Personal Security Environment
(PSE). Transaction STRUST is used to maintain the PSE.
Determine required certificate
If a call to an IBM Cloud service failed due to a missing SSL
certificate, check the ICM trace file to find the required
certificate. To do so, call transaction SMICM and select menu item
Goto → Trace File → Display End. Alternatively, call
transaction AL11 and navigate to file DIR_HOME/dev_icm. Find last
entry in trace file that indicates error
SSSLERR_PEER_CERT_UNTRUSTED, as shown in the example below.
[Thr nn] Peer not trusted
[Thr nn] Certificate:
[Thr nn] Certificate:
[Thr nn] Subject: CN=*.watsonplatform.net, O=INTERNATIONAL BUSINESS MACHINES CORPORATION, L=Armonk, SP=New York, C=US
[Thr nn] Issuer: CN=GeoTrust RSA CA 2018, OU=www.digicert.com, O=DigiCert Inc, C=US
[Thr nn] Serial Number: 05:1C:46:1B:6E:C2:29:48:BD:F0:03:B3:A6:87:1A:5B
[Thr nn] Verification result:
[...]
[Thr nn] SignerCert:
[Thr nn] Certificate:
[Thr nn] Subject: CN=GeoTrust RSA CA 2018, OU=www.digicert.com, O=DigiCert Inc, C=US
[Thr nn] Issuer: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
[Thr nn] Serial Number: 05:46:FE:18:23:F7:E1:94:1D:A3:9F:CE:14:C4:61:73
[Thr nn] Verification result:
[...]
[Thr nn] SignerCert:
[Thr nn] Certificate:
[Thr nn] Subject: CN=DigiCert Global Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US
[...]
[Thr nn] << ---------- End of Secu-SSL Errorstack ----------
[Thr nn] Target Hostname="stream.watsonplatform.net"
[Thr nn] SSL NI-hdl 463: local=9.152.20.145:56542 peer=169.48.115.62:443
[Thr nn] <<- ERROR: SapSSLSessionStartNB(sssl_hdl=3fef0000c70)==SSSLERR_PEER_CERT_UNTRUSTED
[Thr nn] *** ERROR => SSL handshake with stream.watsonplatform.net:443 failed: SSSLERR_PEER_CERT_UNTRUSTED (-102)
[Thr nn] The peer's X.509 Certificate (chain) is untrusted
The SSL error stack shows the SSL certificate chain, which in the
example above looks like follows:
| Certificate Authority Type | Certificate Authority (CA) |
|---|
| end-user | *.watsonplatform.net |
| intermediate | GeoTrust RSA CA 2018 |
| root | DigiCert Global Root CA |
You can install any of these SSL certificates. However, it is
recommended to install the root CA certificate.
Download the
appropriate SSL certificate from the provider's website, for example
https://www.digicert.com/digicert-root-certificates.htm. Store the
certificate file on your computer.
Add an SSL certificate to the PSE
Proceed as follows to add the downloaded SSL certificate to your SAP
system's Standard SSL Client PSE.
- Logon to the SAP system and call transaction STRUST.
- Switch to edit mode (press according tool bar icon).
- If a local PSE file does not exist already, create it by
right-clicking on
SSL client SSL Client (Standard) and selecting
Create from context menu. Keep all default settings in next popup
dialog.
- In Certificate section, click Import (alternatively select menu
item Certificate → Import). Choose the certificate file
that you have downloaded and import the certificate.
- Click button Add to Certificate List.
- Click Save (F3).
Restart the ICM (Internet Communication Manager)
It is recommended to restart the ICM after a new SSL certificate has
been applied to the PSE. To do so, proceed as follows.
- Logon to the SAP system and start transaction SMICM.
- If applicable, ensure that the ICM is restarted automatically when ended:
Administration → ICM → Restart → Yes.
- Select menu item Administration → ICM → Exit Soft
→ Global.
Credentials
Before you can access a specific service from your SAP system, you
must create a service instance in the IBM Cloud and
obtain an API key.
The API key can be shared among multiple end users of the SAP system, but
you must ensure that the selected plan is sufficient to support the expected
number of calls or the expected data volume.
All currently supported services support IAM authentication (see
below). Service credentials consist of an API key and a URL. Both the
API key and the URL are character values that need to be provided as parameters
i_apikey and i_url to method zcl_ibmx_service_ext=>get_instance.
You can store the values with your application, but it is suggested to
do that in an encrypted format. Using cloud services usually creates
costs based on usage for the owner of the service instance, and anyone
with the credentials can use the service instance at the owner's
expenses. If you want to distribute the costs over multiple cost
centers, you need to create a service instance and provide service
credentials for each cost center separately.
Configuration table
Service credentials and other parameters that must be specified at
watsonx service wrapper ABAP class instantiation can also be provided
in table ZIBMX_CONFIG. This table has three keys:
| Table Key | Description |
|---|
| SERVICE | The ABAP class name without prefix ZCL_IBMX_ |
| INSTANCE_UID | ID chosen by application developer that must be provided by application as parameter to method zcl_ibmx_service_ext=>get_instance() |
| PARAM | The parameter name |
List of configuration parameters in table ZIBMX_CONFIG
| Parameter Name | Default Value | Description |
|---|
| URL | service-dependent | watsonx service url |
| APIKEY | | watsonx service API keys |
| PROXY_HOST | | Proxy server |
| PROXY_PORT | | Proxy server port |
| AUTH_NAME | service-dependent | Authorization, IAM or basicAuth |
| SSL_ID | CLIENT | SSL identity, defines PSE for SSL certificates: CLIENT or ANONYM |
IAM Authentication
Identity and Access Management (IAM) is a bearer-token based
authentication method. Token management is either performed by the
ABAP SDK or must be implemented by the SDK user.
If a value for
i_apikey is provided by the caller in method
zcl_ibmx_service_ext=>get_instance(), the ABAP SDK generates a
bearer-token under the cover when needed and refreshes it when it is
about to expire.
If i_apikey is not provided for method
zcl_ibmx_service_ext=>get_instance(), the ABAP SDK user must
implement an individual token management. Before a service method is
called the first time, a valid bearer-token must be provided to the
watsonx service wrapper ABAP class instance as follows:
lo_service_class->set_bearer_token( i_bearer_token = '...' ).
Afterwards, service methods can be called as long as the provided
token is valid. When the token has expired, the method above must be
called again with a new (refreshed) bearer-token as parameter.
Usage
The client library is delivered as package ZIBMX. Once the Git
repository has been cloned to the SAP system, a watsonx service
instance is wrapped by an ABAP class instance.
The following
watsonx services are currently supported:
| Service | ABAP Class Name |
|---|
| watsonx.ai Runtime | ZCL_IBMX_WML_V4 |
| watsonx.ai | ZCL_IBMX_WATSONX_AI_ML_V1 |
Using the client library requires two steps:
-
Create an instance of the watsonx service wrapper ABAP class by
calling method zcl_ibmx_service_ext=>get_instance.
data:
lo_service_class type <ABAP Class Name>.
zcl_ibmx_service_ext=>get_instance(
exporting
i_url = <url>
i_apikey = <api key>
...
importing
eo_instance = lo_service_class ).
Note
To keep this page readable, only the first part of the README is shown. Open the original README for the full document.