com.ibm.di.connector.sapr3.bor
Class SapR3BorConnector

java.lang.Object
  com.ibm.di.connector.Connector
      com.ibm.di.connector.sapr3.bor.SapR3BorConnector

All Implemented Interfaces:

ConnectorInterface, AbapErrorCache, VersionInfoInterface

public final class SapR3BorConnector
extends Connector
implements ConnectorInterface, AbapErrorCache

The SAP R/3 Business Object Repository Connector. Version %sapborcn.release.version% Build %sapborcn.release.build.version%.

The connector enables external applications, using TDI, to access BOR objects in SAP R/3. It supports the following TDI Connector Modes: Add Only, Delete, Update, Iterator, Lookup. The connector supports design time schema query via querySchema(java.lang.Object).

A note about ABAP errors and warnings
The connector invokes BAPI/RFC functions in SAP to perform the connector mode operations. In some cases, data passed to the BAPI/RFC functions from the XML input, may result in ABAP data validation failures. The BAPI/RFC functions return the results of validation checks in the "RETURN" parameter of the RFC.

The connector has been desingned to make the RFC return status available to the Assembly Line. The connector does not interpret, or translate, ABAP errors or warnings into thrown exceptions. The connector registers a script bean named "borcAbapErrorCache". The bean is registered for all connector modes and can be accessed in connector hooks. The bean is an instance of AbapErrorCache. Script code in a connector hook can use this information to perform contingency actions as required. The cache is reset before the execution of each connector method. Example script code is shown below:

var errs = borcAbapErrorCache.getLastErrorSet();
if (errs.size() > 0) {
task.logmsg("********** There were ABAP Errors *********");
for (var i = 0; i < errs.size(); ++i) {
var errInfo = errs.get(i);
task.logmsg("The message is: " + errInfo.getMsg());
task.logmsg("The message number is: " + errInfo.getMsgNum().toString());
}
}

var warns = borcAbapErrorCache.getLastWarningSet();
if (warns.size() > 0) {
task.logmsg("********** There were ABAP Warnings *********");
for (var i = 0; i < warns.size(); ++i) {
var errInfo = warns.get(i);
task.logmsg("The message is: " + errInfo.getMsg());
task.logmsg("The message number is: " + errInfo.getMsgNum().toString());
}
}


A given SAP entry is represented as XML by the connector, and is set as the value of the connector attribute named "sapXml". The value of this attribute is always an XML string. Its XSchema is defined in the user guide for the connector. The format of the XML may be altered by modifying the XSL style sheets that are configured for the connector.

The configuration parameters of the connector are described below. The runtime parameters appear within braces ():

R3 Client (client)
SAP R/3 Logon client for R/3 connection (for example, 100). This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

R3 User (user)
SAP R/3 Logon user for R/3 connection. This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

Password (passwd)
SAP R/3 Logon password for R/3 connection. This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

R3 System Number (sysnr)
The SAP R/3 system number for R/3 connection (for example, 100). This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

R3 Hostname (ashost)
SAP R/3 application server name for R/3 connection. This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

Gateway host (gwhost)
Gateway host name for R/3 connection. This is passed directly to the Tivoli Directory Integrator SAP R/3 RFC Function Component.

RFC Trace (trace)
Set to one (1) to enable RFC API tracing. If enabled, the SAP RFC API will produce separate rfc_nnnn.trc files in the working directory of Tivoli Directory Integrator. This option may be useful to help diagnose RFC invocation problems. It logs the activity and data between the Connector and SAP R/3. This should be set to zero (0) for production deployment.

BOR Class Name (sapr3.conn.borObjName)
The name of the BOR class that this connector will be integrating. The names of BOR classes are available using transaction BAPI in SAP R/3. This value is used to obtain the keyfield names of the BOR object when a schema query is performed.

RFC Function Component Name (sapr3.conn.rfcFC)
The name of the RFC Function Component registered with Tivoli Directory Integrator. This option should be changed only on the advice of IBM support. The default value is: ibmdi.SapR3RfcFC

Add Mode StyleSheets (sapr3.conn.putStylesheets)
The list of XSLT style sheets files to be executed by the Connector when deployed in Add Only mode. Each XSLT file must be separated by a new line within the text box. At runtime, each style sheet is applied to the XML contained within the Container Entry. The XSL will be applied to the value of the attribute named sapXml. This configuration parameter should be changed only at the direction of IBM support.

Modify Mode StyleSheets (sapr3.conn.modifyStylesheets)
The list of XSLT style sheets files to be executed by the Connector when deployed in Modify mode. Each XSLT file must be separated by a new line within the text box. At runtime, each style sheet is applied to the XML contained within the Container Entry. The XSL will be applied to the value of the attribute named sapXml. This configuration parameter should be changed only at the direction of IBM support.

Delete Mode StyleSheets (sapr3.conn.deleteStylesheets)
The list of XSLT style sheets files to be executed by the Connector when deployed in Delete mode. Each XSLT file must be separated by a new line within the text box. At runtime, each style sheet is applied to the XML contained within the Container Entry. The XSL will be applied to the value of the attribute named sapXml. This configuration parameter should be changed only at the direction of IBM support.

Lookup Mode Pre StyleSheet (sapr3.conn.findPreStylesheet)
The XSLT style sheet file to be executed by the Connector when creating an RFC XML request able to obtain all user attributes for a given user. This configuration value must be set when the Connector is deployed in Update, Delete, and Lookup modes. This configuration parameter should be changed only at the direction of IBM support.

Lookup Mode Post StyleSheet (sapr3.conn.findPostStylesheet)
The XSLT style sheet file to be executed by the Connector when creating the user XML formatted response from the Connector. This configuration value must be set when the Connector is deployed in Update, Delete, and Lookup modes. The XSLT transforms the response XML from the RFC executed as a result of the XSLT from Lookup Mode Pre StyleSheet configuration. This configuration parameter should be changed only at the direction of IBM support.

Select Entries Pre StyleSheet (sapr3.conn.selectEntriesPreStylesheet)
The XSLT style sheet file to be executed by the Connector when creating an RFC XML request able to obtain all user names from SAP. This configuration value must be set when the Connector is deployed in Iterator mode. This configuration parameter should be changed only at the direction of IBM support.

Select Entries Post StyleSheet (sapr3.conn.selectEntriesPostStylesheet)
The XSLT style sheet file to be executed by the Connector when creating the user XML for the getNextEntry() processing. This configuration value must be set when the Connector is deployed in Iterator mode. The XSLT transforms the response XML from the RFC executed as a result of the XSLT from Select Entries Pre StyleSheet configuration. This configuration parameter should be changed only at the direction of IBM support.

Iterator Mode Pre StyleSheet (sapr3.conn.getNextPreStylesheet)
The XSLT style sheet file to be executed by the Connector when creating an RFC XML request able to obtain all user attributes for a given user. This configuration value must be set when the Connector is deployed in Iterator mode. This configuration parameter should be changed only at the direction of IBM support.

Iterator Mode Post StyleSheet (sapr3.conn.getNextPostStylesheet)
The XSLT style sheet file to be executed by the Connector when creating the user XML formatted response from the Connector. This configuration value must be set when the Connector is deployed in Iterator mode. The XSLT transforms the response XML from the RFC executed as a result of the XSLT from Iterator Mode Pre StyleSheet configuration. This configuration parameter should be changed only at the direction of IBM support.

For a description of Add Only mode requirements, see putEntry(com.ibm.di.entry.Entry).

For a description of Update mode requirements, see modEntry(com.ibm.di.entry.Entry, com.ibm.di.server.SearchCriteria).

For a description of Delete mode requirements, see deleteEntry(com.ibm.di.entry.Entry, com.ibm.di.server.SearchCriteria).

For a description of Lookup mode requirements, see findEntry(com.ibm.di.server.SearchCriteria).

For a description of Iterator mode requirements, see getNextEntry() and selectEntries().

Field Summary

Fields inherited from class com.ibm.di.connector.Connector

ALL_MODES, myLog, PROPERTY_MESSAGE, PROPERTY_READER, PROPERTY_WRITER

Constructor Summary

SapR3BorConnector()
Construct the Connector.

Method Summary

void	deleteEntry(Entry entry, SearchCriteria search) Called by TDI AL to remove an existing user and associated attributes from SAP R/3
Entry	findEntry(SearchCriteria search) Called by TDI AL to find an existing BOR object instance and associated attributes in SAP R/3.
List	getLastErrorSet() Allows the caller to obtain a list of ABAP errors that might have occured during the execution of any supported Connector method.
List	getLastWarningSet() Allows the caller to obtain a list of ABAP warnings that might have occured during the execution of any supported Connecotor method.
Entry	getNextEntry() This method is called to retrieve the next entry from the connector.
String	getVersion() Get the version string.
void	initialize(Object o) This method is called once after the connector configuration file has been provided by the caller.
void	modEntry(Entry entry, SearchCriteria search) Called by TDI AL to update an existing user and associated attributes in SAP R/3
void	putEntry(Entry entry) Called by TDI AL to add a new entry and associated attributes to SAP R/3.
Object	querySchema(Object source) Return the TDI Entry schema supported by this connector.
void	registerScriptBeans(ScriptEngine se) This method is called to register specific objects in the script context.
void	selectEntries() Called by TDI AL when the connector operates in Iterator mode inside an assembly line.

Methods inherited from class com.ibm.di.connector.Connector

addFindEntry, allModes, clearFindEntries, debug, debugMode, findEntry, getBoolean, getClassInstance, getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getLog, getMaxDuplicateEntries, getModes, getModes, getName, getNextClient, getNextFindEntry, getParam, getParser, getProperty, getPushbackEntry, getRawConnectorConfiguration, getRSInterface, hasConfigValue, hasParser, initParser, isDeltaSupported, isExceptionFatal, isIOException, logmsg, modEntry, pushback, queryOperations, queryReply, queryTables, reconnect, reconnect, replyEntry, setConfiguration, setContext, setCurrent, setLog, setMaxDuplicateEntries, setModes, setModes, setName, setParam, setParser, setProperty, setRSInterface, terminate, terminateServer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.ibm.di.connector.ConnectorInterface

getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getMaxDuplicateEntries, getName, getNextClient, getNextFindEntry, getParam, getPushbackEntry, getRawConnectorConfiguration, isDeltaSupported, isExceptionFatal, isIOException, modEntry, pushback, queryOperations, queryReply, reconnect, replyEntry, setConfiguration, setContext, setCurrent, setLog, setMaxDuplicateEntries, setName, setParam, setRSInterface, terminate, terminateServer

Constructor Detail

SapR3BorConnector

public SapR3BorConnector()

Construct the Connector.

Method Detail

getLastWarningSet

public List getLastWarningSet()

Allows the caller to obtain a list of ABAP warnings that might have occured during the execution of any supported Connecotor method.

Specified by:

getLastWarningSet in interface AbapErrorCache

Returns:

a list of AbapErrorInfo objects at warning severity. Minimum length will be zero.

getLastErrorSet

public List getLastErrorSet()

Allows the caller to obtain a list of ABAP errors that might have occured during the execution of any supported Connector method.

Specified by:

getLastErrorSet in interface AbapErrorCache

Returns:

a array of error severity errors. Minimum length will be zero.

registerScriptBeans

public void registerScriptBeans(ScriptEngine se)
                         throws Exception

Description copied from class: Connector

This method is called to register specific objects in the script context. If the connector has a parser, the parser's registerScriptBeans method is also called.

Specified by:

registerScriptBeans in interface ConnectorInterface

Overrides:

registerScriptBeans in class Connector

Parameters:

se - The script engine context

Throws:

Exception

initialize

public void initialize(Object o)
                throws SapR3ConnectorException,
                       ConfigurationException

This method is called once after the connector configuration file has been provided by the caller.

Specified by:

initialize in interface ConnectorInterface

Overrides:

initialize in class Connector

Parameters:

o - TDI config object. Not used.

Throws:

SapR3ConnectorException - When an error happens during super class init.

ConfigurationException - if SAP connection parameters are invalid or XSL files are invalid.

querySchema

public Object querySchema(Object source)
                   throws SapR3ConnectorException

Return the TDI Entry schema supported by this connector. The connector supports one native attribute named "sapXml". sapXml is an XML string representing the attributes of a BOR object to be operated on.

Other attributes reflect the given BOR object keyfield names . A typical example of extra attributes would be the specification of BOR object key fields. They are supported to allow the definition of TDI "LinkCriteria" when the connector is deployed in Lookup, Delete, or Update modes.

Specified by:

querySchema in interface ConnectorInterface

Overrides:

querySchema in class Connector

Parameters:

source - not used.

Returns:

A vector containg one Entry for TDI schema display.

Throws:

SapR3ConnectorException - If an error occurs.

See Also:

Entry, Vector

putEntry

public void putEntry(Entry entry)
              throws ConnectorMethodException,
                     SapR3ConnectorException

Called by TDI AL to add a new entry and associated attributes to SAP R/3.

Specified by:

putEntry in interface ConnectorInterface

Overrides:

putEntry in class Connector

Parameters:

entry - The AL connector entry input. This connector must have an attribute named "sapXml". Its value must be an XML string conforming to the SAP XML Schema. The XML is transformed by the XSL style sheets into mulitple RFC requests that altimately create the entry in SAP R/3.
See user guide for more details.

Throws:

SapR3ConnectorException - If the attribute is missing from the entry.

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.putEntry(com.ibm.di.entry.Entry)

deleteEntry

public void deleteEntry(Entry entry,
                        SearchCriteria search)
                 throws ConnectorMethodException,
                        SapR3ConnectorException

Called by TDI AL to remove an existing user and associated attributes from SAP R/3

Specified by:

deleteEntry in interface ConnectorInterface

Overrides:

deleteEntry in class Connector

Parameters:

entry - The AL connector entry input. This connector must have an attribute named "sapXml". Its value must be an XML string conforming to the SAP XML Schema supported by the configured XSL style sheets.
See user guide for more details.

search - Passed through to XSL style sheet as an XSL param. Typically, the search criteria include the keyfields of the given BOR object to be deleted.

Throws:

SapR3ConnectorException - If the attribute is missing from the entry.

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.deleteEntry(com.ibm.di.entry.Entry, com.ibm.di.server.SearchCriteria)

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search)
              throws ConnectorMethodException,
                     SapR3ConnectorException

Called by TDI AL to update an existing user and associated attributes in SAP R/3

Specified by:

modEntry in interface ConnectorInterface

Overrides:

modEntry in class Connector

Parameters:

entry - The AL connector entry input. This connector must have an attribute named "sapXml". Its value must be an XML string conforming to the SAP User XML Schema. supported by the configured XSL style sheets.
See user guide for more details.

search - Passed through to XSL style sheet as an XSL param. Typically, the search criteria include the keyfields of the given BOR object to be modified.

Throws:

SapR3ConnectorException - If the attribute is missing from the entry.

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.modEntry(com.ibm.di.entry.Entry, com.ibm.di.server.SearchCriteria)

findEntry

public Entry findEntry(SearchCriteria search)
                throws ConnectorMethodException,
                       SapR3ConnectorException

Called by TDI AL to find an existing BOR object instance and associated attributes in SAP R/3.

Specified by:

findEntry in interface ConnectorInterface

Overrides:

findEntry in class Connector

Parameters:

search - Defined in the "LinkCriteria" tab of the AL. Must have a criteria names matching the key field names of the BOR object as required by the given BOR read methods.

Returns:

The entry populated with attribute "sapXml", or null if the BOR object instance could not be found.

Throws:

SapR3ConnectorException - If the attribute is missing from the entry.

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.findEntry(com.ibm.di.server.SearchCriteria)

selectEntries

public void selectEntries()
                   throws ConnectorMethodException,
                          SapR3ConnectorException

Called by TDI AL when the connector operates in Iterator mode inside an assembly line. It finds all BOR object identifiers currently managed by the connected SAP R/3 instance. It stores all instance ID names and values in a cached BorInstanceIdIterator following an RFC lookup to obtain the names.

The XML value returned from the post XSL, must have an elements named "sapBorObjIdentifier". The children of this element must be elements where the tagnames match the keyfields of the given BOR object.

Specified by:

selectEntries in interface ConnectorInterface

Overrides:

selectEntries in class Connector

Throws:

SapR3ConnectorException - If the attribute is missing from the entry.

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.selectEntries()

getNextEntry

public Entry getNextEntry()
                   throws ConnectorMethodException

This method is called to retrieve the next entry from the connector. When there are no more entries to retrieve the function should return a null value indicating a logical end of file. This method uses the cached Iterator from selectEntries().

Specified by:

getNextEntry in interface ConnectorInterface

Overrides:

getNextEntry in class Connector

Returns:

An entry containing sapXml attribute. Its value is an XML string representing the BOR object instance attributes. The result will be null when no more instances are available.

Throws:

ConnectorMethodException - if the SAP network call fails, or an XSL transform error occurs.

See Also:

Connector.selectEntries()

getVersion

public String getVersion()

Get the version string. Used by TDI to log version info at AL startup.

Specified by:

getVersion in interface VersionInfoInterface

Returns:

The version info string for this connector.