SAP JCo Adapter

The SAP JCo adapter is used to access, retrieve, and modify data in on-premise SAP systems from RunMyProcess DigitalSuite by means of the SAP Java Connector (JCo), version 3.x. SAP JCo is a development library provided by SAP that enables Java applications to communicate with on-premise SAP systems by Business API (BAPI) and Remote Function Calls (RFC) on SAP's RFC protocol.

Overview

The following illustration shows the components involved in the communication between RunMyProcess DigitalSuite and SAP as well as the request and response format conversions between them:

communication

The SAP JCo adapter supports two types of connections with SAP: "with pool" and "without pool".

For establishing a connection with SAP, two sets of parameters are required: input parameters and configuration parameters. The input parameters, SAP authorization and request information, are sent through the body of the RunMyProcess requests. The configuration parameters, SAP server information/destination parameters, are maintained in the SAP JCo adapter's configuration file.

SAP JCo and the SAP JCo adapter are generic, carrying out conversions, re-formatting, and re-arrangements as required. They support:

Different BAPIs of SAP: standard BAPIs, modified BAPIs, custom BAPIs, BAPIs with or without parameters. The only requirement is that the BAPI is accessible through SAP JCo and that BAPI metadata is available in the JCo repository.
All types of BAPI parameters: import parameters, export parameters, table parameters, changing parameters
Any number of parameters
14 ABAP data types
All parameter field types: field, structure, table

The SAP JCo adapter can send back its responses to RunMyProcess DigitalSuite in JSON or XML format. Except for errors that occurred, the output is encoded in Base64.

Prerequisites

The following prerequisites must be fulfilled to install and run the SAP JCo adapter:

You must install the adapter on a local system in your environment. This can either be the system where you have installed the DigitalSuite EnterpriseConnect Agent, or a different one which is able to connect to the Agent's host.
You can install the adapter several times in your environment, for example, to work with different SAP installations. The identifier of the adapter (protocol setting in the handler.config configuration file) must be unique for each of the installations.
SAP JCo, Version 3.x, must be installed on the system where you want to run the adapter. It must be installed as a stand-alone component, not as a version integrated with "SAP Business Connector" or "AS Java".

SAP JCo is provided and maintained by SAP. As an SAP customer, you can download SAP JCo from https://support.sap.com/en/product/connectors/jco.html. Install SAP JCo as described in the installation instructions on the download site and in the archive. The installation folder will be referred to as [sap-jco] in the following descriptions.

To make sure if SAP JCo is installed correctly, you can start its "About" dialog, for example, by calling:

java -jar [sap-jco]/sapjco3.jar on Windows, or

java -jar [sap-jco]/sapjco3.jar -stdout on Linux
The SAP installation you want to work with (SAP application, message, and gateway servers, or the SAP router) must be accessible by SAP JCo from the system where it is installed together with the DigitalSuite EnterpriseConnect SAP JCo adapter.

Installing the Adapter

To install the adapter:

Download the following ZIP file: unified-adapter-[version].zip

[version] is the current version number

The ZIP file contains executables, licences, configuration files, and reference files for several adapters.
Extract the ZIP file to a local folder. The following path is recommended:

[parent-folder]\adapters\sap

[parent-folder] is a folder of your choice. If the EnterpriseConnect Agent is installed on the same machine, use its installation folder as the [parent-folder], for example, C:\ProgramFiles (x86)\dsec-agent.
Copy the configuration files for the SAP JCo adapter, JCO3.config and handler.config, from the configFiles\sap.reference subfolder to the configFiles folder, for example:
```
copy configFiles\sap.reference\*.config configFiles
```
Overwrite existing files in the configFiles folder.

Depending on the operating system, copy the following files from your SAP JCo installation to the lib folder:

Microsoft Windows:

copy [sap-jco]\sapjco3.dll lib     
copy [sap-jco]\sapjco3.jar lib

Linux:

copy [sap-jco]/libsapjco3.so lib     
copy [sap-jco]/sapjco3.jar lib

If desired, delete obsolete files. Only the following folders and files are required in the sap folder to use the adapter:
```
sap
├── configFiles
│   ├── handler.config
│   └── JCO3.config
├── lib
│   ├── sapjco3.dll (Windows) or libsapjco3.so (Linux)
│   ├── sapjco3.jar
│   └── unified-adapter-[version].jar
└── log.properties
```
In addition, we recommend you keep the following:
- runAdapter.bat batch file for starting the adapter on Microsoft Windows
- sap.reference subfolder in the configFiles folder for reference purposes

Configuring the Adapter

Configuration settings for the SAP JCo adapter are required in the following configuration files:

handler.config
JCO3.config

Edit the files with a plain text editor.

handler.config

The handler.config file contains general configuration settings for connecting the adapter to the EnterpriseConnect Agent:

#Generic Protocol Configuration
protocol = JCO3
protocolClass = org.runmyprocess.sec2.JCO3
agentHost = 127.0.0.1:8080
pingFrequency = 1000
adapterConnectionInterval = 1000
offlineLogsMaxSize = 100
maxNumberOfLogsInBatch = 100
clusterEnabled = false
clusterAgentsHttpAddressList = localhost:8071,localhost:8072,localhost:8073

The settings have the following meaning:

protocol: The identifier of the adapter. If you install the adapter several times in your environment, the identifier must be unique for each of the installations, for example, JCO31 and JCO32.
protocolClass: The adapter's Java class.
agentHost: The IP address and port of the EnterpriseConnect Agent.
pingFrequency: The frequency in milliseconds in which the adapter pings the EnterpriseConnect Agent.
adapterConnectionInterval: The frequency in milliseconds in which the adapter tries to connect to the EnterpriseConnect Agent.
offlineLogsMaxSize: The maximum number of log entries that the adapter collects locally and sends to the EnterpriseConnect Agent when it re-connects to it after it was disconnected.
maxNumberOfLogsInBatch: The maximum number of log entries the adapter sends to the EnterpriseConnect Agent at a time. A value of 0 means that the number of log entries sent at a time is unlimited.
clusterEnabled: true if the EnterpriseConnect Agent is configured and running as a cluster, false otherwise.
clusterAgentsHttpAddressList: The IP addresses and ports of the EnterpriseConnect Agent cluster, if clusterEnabled is set to true.

JCO3.config

The JCO3.config file contains specific settings for the adapter:

#SAP Servcer Connection Configuration   
JCO_ASHOST = 10.10.0.10 
JCO_SYSNR = 01
JCO_CLIENT = 321
JCO_LANG = en
JCO_POOL_CAPACITY  = 3
JCO_PEAK_LIMIT = 10

The settings have the following meaning:

JCO_ASHOST: The host name or IP address of the SAP application server to work with.
JCO_SYSNR: The two-digit system number, e.g. 01.
JCO_CLIENT: The three-digit number identifying the SAP client to work with in the SAP system, e.g. 321. A client is a self-contained unit in an SAP system with separate master records and its own set of tables.
JCO_LANG: The two-character ISO language code specifying the logon language, e.g. EN, DE, FR
JCO_POOL_CAPACITY: The maximum number of idle connections to keep open.
JCO_PEAK_LIMIT: The maximum number of active connections that can simultaneously be created.

Starting the Adapter

The adapter needs to be running to be able to work with the SAP installation.

Before you start the adapter, make sure that the DigitalSuite EnterpriseConnect Agent is running.

To start the adapter:

Change to the sap installation folder.
Execute the following command, depending on the operating system:
- On Microsoft Windows: Execute the runAdapter.bat batch file.
- On Linux: Execute the following command directly, or create and execute a corresponding shell script to do so:
```
java -XX:+UseG1GC -XX:+ExitOnOutOfMemoryError -Djava.util.logging.config.file=./log.properties -cp "lib/*:" org.runmyprocess.sec2.AdapterHandler
```

Using the Adapter

If everything is configured and running correctly, you can execute BAPIs in SAP from RunMyProcess DigitalSuite through the EnterpriseConnect Agent and the SAP JCo adapter.

Request: POST on http://[agent-host]:[port]/, where [agent-host] and [port] are the IP address and port of the EnterpriseConnect Agent.

Content Type: application/json

Accept: application/json

A 200 OK status in the result indicates that information was sent and received by the SAP JCo adapter.

Except for errors that occurred, the response is encoded in Base64. You can use the RunMyProcess Freemarker functions or JavaScript SDK to decode the information.

Content (examples):

The message body is a JSON (JavaScript Object Notation) object whose structure depends on the operation to be executed. Each operation requires a nested JSON object with the outer object specifying the protocol, and the inner object defining the operation-specific parameters, for example:

{
"protocol":"JCO3",
"data":{
        "SAPUser":"<username>",
        "SAPPassword":"<password>",
        "serviceName":"ABAP_AS_WITH_POOL",
        "functionName":"BAPI_USER_GET_DETAIL",
        "importParameters": 
        {
            "USERNAME": "<username>"
        }
    }
}

Usually, you will need to specify authentication information for SAP, like SAPUser and SAPPassword in the example. The BAPI BAPI_USER_GET_DETAIL returns details about the user specified as the import parameter.

More details on handling specific cases and issues are provided in the following subsections. You can also find a sample request in the sap.reference\InputJSONExample.txt file in the sap installation folder.

Specifying Parameter Field Types

The fields of any BAPI parameter (import, export, table, or changing parameter) can be one of the following types: simple field, structure, or table. The following examples show how to specify each of these types in the JSON requests to SAP.

Simple field (key and value pair) in BAPI:

The JSON value must by a string value enclosed in double quotes ("").

Example:

"importParameters" : {
    "<field1>" : "<field1_value>",
    "<field2>" : "<field2_value>",
    "<field..>" : "<field.._value>",
    "<field..n>" : "<field..n_value>"
}

Structure (collection of simple fields and/or nested structures) in BAPI:

The JSON value must be a JSON object ({}). For nested structures, the JSON objects can be nested accordingly.

Example:

"importParameters" : {
    "structure_name_1" : {
        "<field1>" : "<field1_value>",
        "<field2>" : "<field2_value>",
        "<field..>" : "<field.._value>",
        "<field..n>" : "<field..n_value>"
    },
    "structure_name_2" : {
        "<field1>" : "<field1_value>",
        "<field2>" : "<field2_value>",
        "<field..>" : "<field.._value>",
        "<field..n>" : "<field..n_value>"
    }
}

Table (relational, record structure) in BAPI:

The JSON value must be a JSON array ([]). For nested tables, the JSON arrays can be nested accordingly. They may include simple fields as well as structures.

Example:

"tableParameters" : {
    "<table_name_1>" : [{
            "<table1row1field1>" : "<table1row1field1_value>",
            "<table1row1field2>" : "<table1row1field2_value>",
            "<table1row1field..>" : "<table1row1field.._value>",
            "<table1row1field..n>" : "<table1row1field..n_value>"
        }, {
            "<table1row2field1>" : "<table1row2field1_value>",
            "<table1row2field2>" : "<table1row2field2_value>",
            "<table1row2field..>" : "<table1row2field.._value>",
            "<table1row2field..n>" : "<table1row2field..n_value>"
        }
    ]
}

Using Parameter Types

In the JSON requests, you can specify all types of BAPI parameters: import parameters, export parameters, table parameters, and changing parameters.

It is not mandatory to pass export parameters in the JSON input. If a BAPI has export parameters you do not need, just pass the ones you are interested in with an empty value (empty string "") in the exportParameters of the JSON input. The SAP JCo adapter will return only these parameters and exclude the other ones.

It is also not mandatory to pass importParameters or tableParameters. A table parameter can have 1-n table rows, which in turn can have 1-n row fields.

Example:

{
    "protocol" : "JCO3",
    "data" : {
        "SAPUser" : "<username>",
        "SAPPassword" : "<password>",
        "serviceName" : "ABAP_AS_WITH_POOL",
        "functionName" : "<name of the BAPI>",
        "importParameters" : {
            "<field1>" : "<field1_value>",
            "<field2>" : "<field2_value>",
            "<field..>" : "<field.._value>",
            "<field..n>" : "<field..n_value>"
        },
        "tableParameters" : {
            "<table_name_1>" :
            [{
                    "<table1row1field1>" : "<table1row1field1_value>",
                    "<table1row1field2>" : "<table1row1field2_value>",
                    "<table1row1field..>" : "<table1row1field.._value>",
                    "<table1row1field..n>" : "<table1row1field..n_value>"
                }, {
                    "<table1row2field1>" : "<table1row2field1_value>",
                    "<table1row2field2>" : "<table1row2field2_value>",
                    "<table1row2field..>" : "<table1row2field.._value>",
                    "<table1row2field..n>" : "<table1row2field..n_value>"
                }
            ],
            "<table_name_2>" :
            [{
                    "<table2row1field1>" : "<table2row1field1_value>",
                    "<table2row1field2>" : "<table2row1field2_value>",
                    "<table2row1field..>" : "<table2row1field.._value>",
                    "<table2row1field..n>" : "<table2row1field..n_value>"
                }, {
                    "<table2row2field1>" : "<table2row2field1_value>",
                    "<table2row2field2>" : "<table2row2field2_value>",
                    "<table2row2field..>" : "<table2row2field.._value>",
                    "<table2row2field..n>" : "<table2row2field..n_value>"
                }
            ]
        }
    }
}

Retrieving BAPI Metadata

You can requst metadata on all known BAPIs from SAP. This is useful, for example, if you are not sure whether a specific BAPI is exposed by SAP or which parameters are required, or if there is no documentation for custom BAPIs.

To obtain the metadata for a BAPI, include the getMetaData parameter with value true in the JSON input. There is no need to specify other parameters.

The SAP JCo adapter returns the parameter structure of the BAPI as well as all available metadata for each parameter, encoded in Base64. For table parameters, the metadata for each table row and field is returned.

Example:

{
    "protocol" : "JCO3",
    "data" : {
        "SAPUser" : "<username>",
        "SAPPassword" : "<password>",
        "serviceName" : "ABAP_AS_WITH_POOL",
        "functionName" : "<name of the BAPI>",
        "getMetaData" : "true"
    }
}

Obtaining XML Output

By default, the SAP JCo adapter returns its output in JSON format, encoded in Base64. If you want to obtain the result in XML format, include the responseType parameter with the value XML in the JSON input. Specify all the other parameters as required.

The SAP JCo adapter returns the output as provided by SAP in XML format with Base64 encoding.

Example:

{
    "protocol" : "JCO3",
    "data" : {
        "SAPUser" : "<username>",
        "SAPPassword" : "<password>",
        "serviceName" : "ABAP_AS_WITH_POOL",
        "functionName" : "<name of the BAPI>",
        "importParameters" : {

            "<field1>" : "<field1_value>",
            "<field..n>" : "<field..n_value>"
        },
        "tableParameters" : {
            "<table_name_1>" :
            [{
                    "<table1row1field1>" : "<table1row1field1_value>",
                    "<table1row1field..n>" : "<table1row1field..n_value>"
                }, {
                    "<table1row2field1>" : "<table1row2field1_value>",
                    "<table1row2field..n>" : "<table1row2field..n_value>"
                }
            ]
        },
        "responseType" : "XML"
    }
}

Considerations

The following sections provide some hints on possibilities and limitations you should consider when working with SAP through the SAP JCo adapter.

Supported BAPIs

The SAP JCo adapter can handle standard, customized, and custom-built BAPIs. The only requirements is that the BAPI is accessible through SAP JCo and BAPI metadata is available in the JCo repository. ction).

The following types of BAPI are supported:

BAPIs for reading data
BAPIs for creating / changing data
BAPIs for mass processing

The SAP JCo adapter cannot handle BAPIs which require data entry from a GUI during execution. Before attempting to call a specific BAPI, you should thus make sure that it does not expect such input.

Database Modifying BAPIs and Commit/Rollback

BAPIs of the "create or modify transaction/master data" nature are referred to as "database modifying BAPIs". As a prudent measure, SAP expects a separate commit or rollback after the execution of such operations. The commit or rollback needs to be carried out in the same session, and usually specific validations are necessary before.

Some BAPIs handle a commit and/or rollback by themselves. Executing such BAPIs from RunMyProcess DigitalSuite is straightforward.

Technically, the SAP JCo adapter can execute a commit or rollback by means of the following BAPIs.

BAPI_TRANSACTION_COMMIT - Execute external commit
BAPI_TRANSACTION_ROLLBACK - Execute external rollback

However, this is not advisable and must be avoided.

If a specific BAPI requires an explicit commit/rollback, the best practice is to write a wrapper with additional logic around the BAPI in SAP and publish it as custom BAPI. Such a custom BAPI can be called safely through the SAP JCo adapter or by any other external application.

Execution of Multiple BAPIs

As a conscious decision, the SAP JCo adapter does not support the execution of multiple BAPIs in one API call.

The reason for this is that DigitalSuite EnterpriseConnect as a whole has a predefined time limit for getting responses to its requests. When this limit is exceeded, the connection is reset and the session lost. Executing multiple BAPIs would increase the probability of such timeouts.

If you intend to execute a sequence of multiple BAPIs, we recommend you enclose them in a wrapper in SAP and call them as a single, custom BAPI.

Simultaneous Calls by Multiple Users

The SAP JCo adapter and DigitalSuite EnterpriseConnect as a whole can handle simultaneous API calls by multiple users, ensuring data consistency and integrity.