Skip to main content

Triggers

The SAP JCo connector supports event-driven integration where the SAP system pushes IDocs or invokes RFC function modules on a registered Ballerina service. Two distinct service types handle these two event categories.

Three components work together:

ComponentRole
sap.jco:ListenerRegisters as a JCo server with the SAP gateway and manages connections
sap.jco:IDocServiceHandles inbound IDocs pushed from SAP
sap.jco:RfcServiceHandles inbound RFC calls invoked by SAP

For action-based operations, see the Action Reference.

Listener​

The sap.jco:Listener establishes the connection and manages event subscriptions.

Configuration​

The listener supports the following connection strategies:

Config TypeDescription
ServerConfigStructured configuration with gateway host, service, program ID, and repository destination
AdvancedConfigRaw JCo property key-value pairs for advanced or non-standard settings

ServerConfig fields:

FieldTypeDefaultDescription
gwhoststringRequiredSAP gateway host to register the server with
gwservstringRequiredSAP gateway service name or port
progidstringRequiredProgram ID registered in the SAP system via transaction SM59
connectionCountint2Maximum number of concurrent RFC connections
repositoryDestinationstring|DestinationConfigRequiredRFC destination used to look up IDoc and RFC metadata. Provide the ID of an already-initialised client or SAP credentials to register an internal destination automatically

AdvancedConfig:

A map<string> of raw JCo property key-value pairs (e.g., "jco.server.gwhost", "jco.server.progid").

Initializing the listener​

Using ServerConfig with inline credentials:

import ballerinax/sap.jco;

configurable jco:ServerConfig sapConfig = ?;

listener jco:Listener sapListener = new (sapConfig);

Using a shared client as the repository destination:

import ballerinax/sap.jco;

configurable jco:DestinationConfig clientConfig = ?;
configurable jco:ServerConfig sapConfig = ?;

final jco:Client jcoClient = check new (clientConfig);
listener jco:Listener sapListener = new (sapConfig);
note

When repositoryDestination is a string, it must match the destinationId of an already-initialised Client. When it is a DestinationConfig, the listener registers an internal JCo destination automatically.

Service​

The connector provides two distinct service types: IDocService for receiving IDocs and RfcService for handling inbound RFC calls. At most one of each kind may be attached to a listener simultaneously.

Callbacks​

IDocService callbacks:

CallbackSignatureDescription
onReceiveremote function onReceive(xml iDoc) returns error?Invoked when an IDoc is received from the SAP system
onErrorremote function onError(error err) returns error?Invoked when a framework-level error occurs (gateway errors, parsing failures)

RfcService callbacks:

CallbackSignatureDescription
onCallremote function onCall(string functionName, jco:RfcParameters parameters) returns jco:RfcRecord|xml|error?Invoked synchronously when SAP calls a function module registered on this server
onErrorremote function onError(error err) returns error?Invoked when a framework-level error occurs (gateway errors, serialization failures)
note

IDoc delivery is fire-and-forget — errors raised by onReceive are logged but not propagated back to SAP. For RfcService, errors returned from onCall surface as ABAP exceptions on the SAP caller side.

Full example — IDoc listener​

import ballerina/io;
import ballerina/data.xmldata;
import ballerinax/sap.jco;

configurable jco:ServerConfig sapConfig = ?;

listener jco:Listener idocListener = new (sapConfig);

service jco:IDocService on idocListener {
    remote function onReceive(xml iDoc) returns error? {
        ORDERS05 iDocRecord = check xmldata:parseAsType(iDoc);
        InternalOrder internalOrder = transform(iDocRecord);
        check processOrder(internalOrder);
    }

    remote function onError(error 'error) returns error? {
        io:println("Error processing iDoc: ", 'error.message());
    }
}

Full example — RFC service​

import ballerina/io;
import ballerinax/sap.jco;

configurable jco:DestinationConfig clientConfig = ?;
configurable jco:ServerConfig sapConfig = ?;

final jco:Client jcoClient = check new (clientConfig);
listener jco:Listener creditCheckListener = new (sapConfig);

service jco:RfcService on creditCheckListener {
    remote function onCall(string functionName, jco:RfcParameters parameters) returns jco:RfcRecord|error {
        if functionName != "Z_CHECK_CUSTOMER_CREDIT" {
            return error("Unsupported function module: " + functionName);
        }
        jco:RfcRecord importParams = parameters.importParameters ?: {};
        string customerId = (importParams["CUSTOMER_ID"] ?: "").toString();
        return {
            "CREDIT_STATUS": "A",
            "CREDIT_SCORE": 750,
            "MESSAGE": "Credit approved for customer " + customerId
        };
    }

    remote function onError(error err) returns error? {
        io:println("SAP gateway error: ", err.message());
    }
}
note

The listener starts asynchronously — a successful start() means the server has been submitted to JCo's scheduler, not that the gateway handshake is complete. If the gateway is unreachable, JCo retries automatically and delivers failures through the onError callback.

Supporting types​

DestinationConfig​

FieldTypeDescription
ashoststringSAP application server host name
sysnrstringSAP system number
jcoClientstringSAP client number
userstringSAP logon user name
passwdstringSAP logon password
langstringSAP logon language (default: "EN")
groupstringSAP logon group for load balancing (default: "PUBLIC")

RfcParameters​

FieldTypeDescription
importParametersRfcRecord?Scalar values and structures sent to SAP as import parameters
tableParametersmap<RfcRecord[]>?Named tables sent to SAP as table parameters

RfcRecord​

An open record of type record {|FieldType?...;|} representing scalar values, structures, or table row data. Field values can be string, int, float, decimal, boolean, time:Date, time:TimeOfDay, byte[], nested records, or record arrays.