08 02 sap connector basics

© SAP AG <Course Number> Unit Title - 1

Connector Framework BasicsUsing the SAP Connector


© SAP AG 2004, Connector Framework Basics – Using the SAP Connector / 2

Course Objectives

After completing this session, you will be able to:

Use the Connector gateway to connect to an R/3 system to retrieve data using the SAP ConnectorIdentify ways to provide credentials to the connectorRetrieve data from a BAPI/RFM using the SAP Connector



How ABAP implements “interface” with RFM?

"Function Modules" are the routines of ABAP program. They have well-defined interfaces called "Import parameters" and "Export parameters". ABAP has 3 data types - Scalar, Structure and Table values. SAP developed it's proprietary communication protocol called "RFC/Remote Function Call", which is originally based on the standard RPC/Remote Procedure Call. We call a RFC-enabled Function Module a "RFM/Remote Function Module". CCI/Common Client Interface API is a Java wrapping layer of RFM.



Connector Framework (for SAP Connector)

Connector Framework Client (for SAP Connector):

Step1. Understand the export/import parameters of Remote Function Modules with SAP Transaction “SE37”.

Step2. Invoke Remote Function Module via Connector Framework API.



Using SE37



Execute Function BAPI_SALESORDER_GETLIST



Execution Results



Display of SALES_ORDERS Table



Display Parameters



Import Parameters – Required and Optional



Using the Connector Framework API

1. Use the Connector Gateway Service to obtain connections to backend systems

2. Use the ConnectionProperties object to facilitate SSO

3. Create an Executable Interaction interface to describe the interaction with the backend system (Function Module, BAPI call,etc.)

4. Create an Interaction Spec (IInteractionSpec) to specify function module to call

5. Create an input record (MappedRecord) describing input parameters

6. Execute the Interaction Spec with the input record

7. Obtain the output (MappedRecord) – usually returns a IRecordset

8. Iterate through recordset and deal with data

CF Basics


The required libraries can be found in the PDK Library convenience ZIP file.


Required imports and libraries

Using the CF Framework requires you to import several packages and add certain libraries to your NWDS project

import com.sapportals.portal.ivs.cg.ConnectionProperties;import com.sapportals.portal.ivs.cg.IConnectorGatewayService;import com.sapportals.portal.ivs.cg.IConnectorService;

import com.sapportals.connector.connection.IConnection;import com.sapportals.connector.execution.structures.*;import com.sapportals.connector.execution.functions.IInteractionSpec;import com.sapportals.connector.execution.functions.IInteraction;import com.sapportals.connector.metadata.structures.IFieldStructure;import com.sapportals.connector.metadata.primitives.IPrimitive;

<PDK>/j2eeclient/activation.jar <PDK>/j2eeclient/connector.jar <PDK>/portalapps/com.sap.portal.ivs.connectorserviceapi.jar <J2EE>/bin/ext/com.sap.genericconnector/GenericConnector.jar<PDK>/j2eeclient/jta.jar



Deployment Descriptor

<property name="ServicesReference" value="com.sap.portal.ivs.connectorservice"/>

Make sure you include a ServicesReference entry to com.sap.portal.ivs.connectorservice in the portalapp.xml deployment descriptor.



Getting a connection - 1

Use the Connector Gateway Service to obtain connections to backend systems

import com.sapportals.portal.ivs.cg.ConnectionProperties;import com.sapportals.portal.ivs.cg.IConnectorGatewayService;import com.sapportals.portal.ivs.cg.IConnectorService;import com.sapportals.connector.connection.IConnection;....IConnectorGatewayService cgService =

(IConnectorGatewayService)PortalRuntime.getRuntimeResources().getService(IConnectorService.KEY);

IConnection con = cgService.getConnection("sapSystem1",request);

...System Alias Request object




Use the ConnectionProperties object to fill in the required connection parameters for SSO.

The Locale is required for language texts, etc. that may be dependent on the user.

The user is required to obtain user mapping info or logon ticket for backend system

import com.sapportals.portal.ivs.cg.ConnectionProperties;

...ConnectionProperties cp = new

ConnectionProperties(request.getLocale(),request.getUser());

...




Use the getConnection() method of the Gateway service to obtain the actual connection to the backend.

There are several ways to obtain the connection. This version requires the System Alias and a ConnectionProperties object

...ConnectionProperties cp = new

ConnectionProperties(request.getLocale(),request.getUser());

connection = cgService.getConnection("SAP_HR",cp);...



Interactions

An Interaction describes the data needed to call a specific function or method in the backend system. It provides a genericinterface to talk to disparate systems and is created via a Connection object.

You must build an InteractionSpec, fill in the required input parameters, then execute the Interaction.

The result will be returned in an output type record

import com.sapportals.connector.execution.functions.IInteractionSpec;import com.sapportals.connector.execution.functions.IInteraction;

...IInteraction ix = connection.createInteractionEx();...



Interaction Specs - 1

An InteractionSpec contains the data needed to call a specific function or method in the backend system.

It is obtained from the Interaction object by calling getInteractionSpec()

import com.sapportals.connector.execution.functions.IInteractionSpec;import com.sapportals.connector.execution.functions.IInteraction;

...IInteraction ix = connection.createInteractionEx();

// Get interaction spec and set the name of the command to runIInteractionSpec ixspec = ix.getInteractionSpec();...



Interaction Specs - 2

After obtaining the InteractionSpec, you need indicate which function/method you wish to call using setPropertyValue();

Next, build an input record (MappedRecord) via the RecordFactory that contains the input parameters for the function/method you intend to call

...// Put Function Name into interaction Properties.ixspec.setPropertyValue("Name",

"BAPI_SALESORDER_GETLIST");

RecordFactory rf = ix.getRecordFactory();

//create input MappedRecord fromMappedRecord input = rf.createMappedRecord("input");input.put("CUSTOMER_NUMBER", custNo);input.put("SALES_ORGANIZATION", salesOrg);...



Set scalar values

MappedRecord input = rf.createMappedRecord("input");input.put("CUSTOMER_NUMBER", custNo);input.put("SALES_ORGANIZATION", salesOrg);

Import Parameter Value



Set Structure values

// Create interactionIInteraction ix = client.createInteractionEx();IInteractionSpec ixSpec = ix.getInteractionSpec();ixSpec.setPropertyValue("Name", "CUSTOMER_SEARCH");

MappedRecord importParams = ix.getRecordFactory().createMappedRecord("input");

// Create IFunction instance

IFunction function = client.getFunctionsMetaData().getFunction("CUSTOMER_SEARCH");



Set Structure values

IStructureFactory structureFactory = ix.retrieveStructureFactory();IRecord structure = (IRecord) structureFactory.getStructure(

function.getParameter("I_SEARCH_FOR").getStructure());structure.setString("MC_NAME", "CARLTON");structure.setString("MC_FIRSTNAME", "W*");

importParams.put("I_SEARCH_FOR", structure);Structure Parameter

Structure Value

Structure Name



Set Table values

. . .

MappedRecord importParams = . . .;

IFunction function = client.getFunctionsMetaData().getFunction("BAPI_MATERIAL_GETLIST");

IStructureFactory structureFactory = ix.retrieveStructureFactory();IRecordSet table = (IRecordSet) structureFactory.getStructure(

function.getParameter("MATNRSELECTION").getStructure());

Structure Name



Set Table values

table.insertRow();table.setString("SIGN","I");table.setString("OPTION","LT");table.setString("MATNR_LOW","10000");table.insertRow();table.setString("SIGN","E");table.setString("OPTION","GT");table.setString("MATNR_LOW","10001");

importParams.put("MATNRSELECTION", table);

Structure Parameter

Structure Value


If you access ABAP data via JCA, the Java data type you need is only "Mapped Record“ type. MappedRecord is a collection of Record instances ordered by key-value pairs. We'll put respective scalar values, structure values, and table values on this MappedRecord instance. MappedRecord belongs to javax.resource.cci.* package.


CF API – Executing the Interaction

After filling in the data for the InteractionSpec, you need execute the Interaction which will cause the CF to make the call to the backend system to obtain or update the data.

The result of the Interaction is returned in an output record (type MappedRecord)

...MappedRecord input = rf.createMappedRecord("input");input.put("CUSTOMER_NUMBER", custNo);input.put("SALES_ORGANIZATION", salesOrg);

MappedRecord output = (MappedRecord)ix.execute(ixspec, input);

...



CF API – Retrieving the Data

The result of the Interaction is returned in an output record (type MappedRecord).

This data structure can contain multiple recordsets.

You obtain a specific recordset by calling get() on the output record

You should check to see that the resulting returned type is the expected datatype

...MappedRecord output = (MappedRecord)

ix.execute(ixspec, input);

Object rs = null;Object result = output.get("SALES_ORDERS");if (result instanceof IRecordSet) {

rs = (IRecordSet) result;}...



CF API – Using the Data

The IRecordSet is very similar to a JDBC type recordset, but is generic and can actually contain tabular data from virtually any type of EIS system

Some methods of the IRecordSet interface:

Sets String value of column numbersetString(int field,String val)

Sets Integer value of field namesetInt(String field, int val)

Get Integer value for fieldgetInt(String field)Get String value for fieldgetString(String field)Get Name of columngetColumnName(int col)Deletes the current rowdeleteRow()

Previous recordprevious()

Next recordnext()



CF API – Using the Data

The recordset also contains metadata (IRecordMetaData) that can be used to dynamically determine column names and other attributes at runtimeIRecordMetaData rsmd = null;try {

rsmd = rs.retrieveMetaData();} catch (Exception ex) {

printException(ex, "Error getting meta data");}// Do something with the Metadata

Get the name of the ColumngetColumnName(int column)Get type of the ColumngetColumnType(int column)

Get text description for the ColumngetColumnLabel(int column)

Get number of ColumnsgetColumnCount()

Some Methods of IRecordMetaData



CF API – Closing the Connection

You need to make sure that you close the connection when you are finished. If you forget to close the connection, then you will quickly run out of connections and the connection pool will be depleted!

It is often good practice to put this in a finally block to ensure that the connection is closed properly.

finally {if (connection != null) {

try {connection.close();logMsg("* Iview: Closing connection ok.");connection = null;

} catch (Exception e) {logMsg("* Iview: Error closing connection.");

}}



Java Documenation

Available in the PDK documentation

Java Development > Javadocs > Connector Framework / Connector Gateway Service



More Information…

SDN Articles:JCA on EP6: Building Portal Applications with Remote Function Modules

PDK Documenation:Java Development -> Portal Development -> Connector Framework

Books:J2EE Connector Architecture and Enterprise Application Integration

Sun Information:http://java.sun.com/j2ee/connector/

J2EE Connector Architecture Industry Supporthttp://java.sun.com/j2ee/connector/download.htmlJ2EE Connector Architecture Brings Business Systems to the Web



Unit Summary

You should now be able to:

Use the Connector gateway to connect to an R/3 system to retrieve data using the SAP ConnectorIdentify ways to provide credentials to the connectorRetrieve data from a BAPI/RFM using the SAP Connector

08 02 sap connector basics

Documents