@sap/cds-rfc

@sap/cds-rfc

An integration plugin for ABAP RFC Function Modules into the SAP Cloud Application Programming Model (CAP). This applies to general RFC-callable Function Modules and to BAPIs.

The plugin contains

• A converter from an RFC interface description to CDS.
• The runtime integration for CAP Node.js.

The integration for CAP Java is covered in a different Java-specific plugin. Currently this is not yet available.

Supported Platforms and Download Channels

This modules uses package @sap-rfc/node-rfc-library for the low-level RFC communication. That package is not available on the standard npmjs.com registry and only available for Linux and Windows.

• macOS users need to use it in a Docker container.

• Only SAP customers can get it through a dedicated NPM registry. In short:

  • An S-user and a license for the SAP Build Code product is required.
  • With this entitlement, you can download NPM credentials for the NODE RFC LIBRARY in the Repository Based Shipment Channel.
  • Your .npmrc file should effectively look like this, with <token> holding the downloaded credentials for the ...repositories.cloud.sap host:

    @sap-rfc:registry=https://...repositories.cloud.sap/
    //...repositories.cloud.sap/:_auth=<token>
    

  Refer to the documentation for the Repository Based Shipment Channel for more, incl. how to get technical users and NPM registry endpoints.

Setup

In a CAP project, install this package:

npm add @sap/cds-rfc

Also update the cds import CLI in @sap/cds-dk to latest:

npm install -g @sap/cds-dk

Usage

Import the RFC API

The RFC interface needs to be converted to a .cds file so that it can be integrated into a CAP application. You can do this through a UI in SAP Business Application Studio or the command line interface (CLI).

In SAP Business Application Studio

Use the Service Center in SAP Business Application Studio to browse and import the RFC interface metadata. See the Service Center documentation for more.

Through the CLI

• Online: The cds import --from rfc CLI allows to connect to an ABAP system and fetch the RFC metadata.

  First, configure the system connection details as documented in Configure System Access.

  Then run:

  cds import --from rfc --as cds --name BAPI_USER_GET_DETAIL --destination SYS
  

  • Use the parameter --force if the same RFC module has already been imported.
  • The destination SYS is just an example and can be any string, but has to match the system credentials.

• Offline: there is also an 'offline' mode available where you need to specify the metadata JSON file as input:

  cds import --from rfc --as cds ./BAPI_USER_GET_DETAIL.json --destination SYS
  

  You can get the metadata file from a previous import run.

  At the moment, there is no general repository available for these files. Such a repository would also not cater to customer-specific modules or extensions to standard modules.

The import operation adds the following to your project:

• A file srv/external/SYS/SYS.cds holding the CDS description of the imported RFC module and the relevant Data Dictionary types. The function module itself is represented as a CDS action that needs to be called at runtime by application code, see Consume in Node.js.

• The RFC metadata as JSON in srv/external/SYS/BAPI_USER_GET_DETAIL.json.

• A service configuration in package.json:

  {
    "requires": {
      "SYS": {
        "kind": "rfc",
        "model": "srv/external/SYS",
        "[production]": {
          "credentials": {
            "destination": "SYS"
          }
        }
      }
    }
  }
  

  The destination name is configured for usage in cloud deployments using the production profile. You need to create this destination in BTP cockpit and provide the system details there.

Consume in Node.js

Write Code to Execute the RFC Action

In your service handler, connect to the RFC service and call the action for the function module:

const cds = require('@sap/cds')
class MyService extends cds.ApplicationService { init() {
   this.on('whateverEvent', async (req) => {

      const sys = await cds.connect.to('SYS') // matches the `requires...` entry in package.json
      const userData = await sys.BAPI_USER_GET_DETAIL({ USERNAME: req.data... })

   })
   return super.init()
}}
module.exports = MyService

The above example uses the convenient typed API sys.BAPI_USER_GET_DETAIL(). Function modules with ABAP namespaces though (like /FOO/BAR) need to be called using the generic send API:

await sys.send('/FOO/BAR', { ... })

As the parameter number of function modules tends to be high, prefer named parameters over positional ones:

await sys.FOO_BAR ({ PARAM1: val1, PARAM1: val2, ... }) // do
await sys.FOO_BAR (val1, val2, ...) // don't, too confusing

Learn more on the different service call styles.

Configure System Access

In local scenarios where you can reach the system from your network, you can skip using destinations and specify the connection details in an .env file:

cds.requires.SYS.credentials.ashost=
cds.requires.SYS.credentials.client=
cds.requires.SYS.credentials.sysnr=00
cds.requires.SYS.credentials.user=
cds.requires.SYS.credentials.passwd=

Such a system configuration is also required for the online CLI importer above.

Make sure to git-ignore this file, if it contains your user and password. You can also pass user and password through environment variables:

 cds_requires_SYS_credentials_user=... cds_requires_SYS_credentials_passwd=... cds watch

On Windows use the SET ... equivalent.

How to Obtain Support

In case you find a bug, please report an incident on SAP Support Portal.

License

This package is provided under the terms of the SAP Developer License Agreement.