Overview  Package   Class  Use  Tree  Serialized  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  extended by com.ibm.di.connector.Connector
      extended by 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 IBM Tivoli Directory Integrator, to access BOR objects in SAP R/3. It supports the following IBM Tivoli Directory Integrator 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 IBM 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 IBM 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 IBM 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 IBM 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 IBM 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 IBM Tivoli Directory Integrator AL to remove an existing user and associated attributes from SAP R/3
 Entry findEntry(SearchCriteria search)
          Called by IBM Tivoli Directory Integrator AL to find an existing BOR object instance and associated attributes in SAP R/3.
 java.util.List getLastErrorSet()
          Allows the caller to obtain a list of ABAP errors that might have occured during the execution of any supported Connector method.
 java.util.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.
 java.lang.String getVersion()
          Get the version string.
 void initialize(java.lang.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 IBM Tivoli Directory Integrator AL to update an existing user and associated attributes in SAP R/3
 void putEntry(Entry entry)
          Called by IBM Tivoli Directory Integrator AL to add a new entry and associated attributes to SAP R/3.
 java.lang.Object querySchema(java.lang.Object source)
           Return the IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator 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, extractExceptionInformation, findEntry, getBoolean, getClassInstance, getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getLog, getMaxDuplicateEntries, getModes, getModes, getName, getNextClient, getNextFindEntry, getParam, getParser, getProperty, getPushbackEntry, getRawConnectorConfiguration, getRSInterface, getUI, hasConfigValue, hasParser, initParser, isDeltaSupported, isExceptionFatal, isIOException, logError, logmsg, modEntry, pushback, queryOperations, queryReply, queryTables, reconnect, reconnect, replyEntry, setConfiguration, setContext, setCurrent, setDebugMode, 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 java.util.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 java.util.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 java.lang.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:
java.lang.Exception - if an error occurs.

initialize

public void initialize(java.lang.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 - IBM Tivoli Directory Integrator 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 java.lang.Object querySchema(java.lang.Object source)
                             throws SapR3ConnectorException

Return the IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator "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 IBM Tivoli Directory Integrator schema display.
Throws:
SapR3ConnectorException - If an error occurs.
See Also:
Entry, Vector

putEntry

public void putEntry(Entry entry)
              throws ConnectorMethodException,
                     SapR3ConnectorException
Called by IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator 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 IBM Tivoli Directory Integrator 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:
ConnectorInterface.selectEntries()

getVersion

public java.lang.String getVersion()
Get the version string. Used by IBM Tivoli Directory Integrator to log version info at AL startup.

Specified by:
getVersion in interface VersionInfoInterface
Returns:
The version info string for this connector.
Overview  Package   Class  Use  Tree  Serialized  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD