com.ibm.di.connector.sapr3.user
Class UserRegistryConnector

java.lang.Object
  com.ibm.di.connector.Connector
      com.ibm.di.connector.sapr3.user.UserRegistryConnector

All Implemented Interfaces:

ConnectorInterface, AbapErrorCache, VersionInfoInterface

public final class UserRegistryConnector
extends Connector
implements ConnectorInterface, AbapErrorCache

The SAP R/3 User Registry Connector. Version %sapurcn.release.version% Build %sapurcn.release.build.version%.

The connector enables external applications, using IBM Tivoli Directory Integrator, to manage users in SAP R/3. It projects the SAP user database as a "registry" into the IBM Tivoli Directory Integrator infrastructure. 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. An example of this case could be the value for post code is not valid within the country region. 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 "urcAbapErrorCache". 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 = urcAbapErrorCache.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 = urcAbapErrorCache.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 user entry is represented as XML by the connector, and is set as the value of the connector attribute named "sapUserXml". The value if this attribute is always an XML string. Its XSchema is defined in the user guide for the connector. An example XML instance is shown below.

  &ltUser&gt
  &ltsapUserName&gt&lt/sapUserName&gt
  &ltsapUserPassword&gt&lt/sapUserPassword&gt
  &ltsapUserAlias&gt
  &ltaliasName&gt&lt/aliasName&gt
  &lt/sapUserAlias&gt     
  &ltsapAddress&gt
  &lttitle&gt&lt/title&gt
  &ltacademicTitle&gt&lt/academicTitle&gt
  &ltfirstName&gt&lt/firstName&gt
  &ltlastName&gt&lt/lastName&gt
  &ltnamePrefix&gt&lt/namePrefix&gt
  &ltnameFormat&gt&lt/nameFormat&gt
  &ltnameFormatRuleCountry&gt&lt/nameFormatRuleCountry&gt
  &ltisoLanguage&gt&lt/isoLanguage&gt
  &ltlanguage&gt&lt/language&gt
  &ltsearchSortTerm&gt&lt/searchSortTerm&gt
  &ltdepartment&gt&lt/department&gt
  &ltfunction&gt&lt/function&gt
  &ltbuildingNumber&gt&lt/buildingNumber&gt
  &ltbuildingFloor&gt&lt/buildingFloor&gt
  &ltroomNumber&gt&lt/roomNumber&gt
  &ltname&gt&lt/name&gt
  &ltname2&gt&lt/name2&gt
  &ltname3&gt&lt/name3&gt
  &ltname4&gt&lt/name4&gt
  &ltcity&gt&lt/city&gt
  &ltpostCode&gt&lt/postCode&gt
  &ltpoBoxPostCode&gt&lt/poBoxostCode&gt
  &ltpoBox&gt&lt/poBox&gt
  &ltstreet&gt&lt/street&gt
  &ltstreetNumber&gt&lt/streetNumber&gt
  &lthouseNumber&gt&lt/houseNumber&gt
  &ltcountry&gt&lt/country&gt
  &ltcountryIso&gt&lt/countryIso&gt
  &ltregion&gt&lt/region&gt
  &lttimeZone&gt&lt/timeZone&gt
  &ltprimaryPhoneNumber&gt&lt/primaryPhoneNumber&gt
  &ltprimaryPhoneExtension&gt&lt/primaryPhoneExtension&gt
  &ltprimaryFaxNumber&gt&lt/primaryFaxNumber&gt
  &ltprimaryFaxExtension&gt&lt/primaryFaxExtension&gt
  &lt/sapAddress&gt
  &ltsapCompany&gt
  &ltcompanyNameKey&gt&lt/companyNameKey&gt
  &lt/sapCompany&gt
  &ltsapDefaults&gt
  &ltstartMenu&gt&lt/startMenu&gt
  &ltoutputDevice&gt&lt/outputDevice&gt
  &ltprintTimeAndDate&gt&lt/printTimeAndDate&gt
  &ltprintDelete&gt&lt/printDelete&gt
  &ltdateFormat&gt&lt/dateFormat&gt
  &ltdecimalFormat&gt&lt/decimalFormat&gt
  &ltlogonLanguage&gt&lt/logonLanguage&gt
  &ltcattTestStatus&gt&lt/cattTestStatus&gt
  &ltcostCenter&gt&lt/costCenter&gt
  &lt/sapDefaults&gt
  &ltsapLogonData&gt
  &ltvalidFromDate&gt&lt/validFromDate&gt
  &ltvalidToDate&gt&lt/validToDate&gt
  &ltuserType&gt&lt/userType&gt
  &ltuserGroup&gt&lt/userGroup&gt
  &ltaccountId&gt&lt/accountId&gt
  &lttimeZone&gt&lt/timeZone&gt
  &ltlastLogonTime&gt&lt/lastLogonTime&gt
  &ltcodeVerEncryption&gt&lt/codeVerEncryption&gt
  &lt/sapLogonData&gt
  &ltsapSncData&gt
  &ltprintableName&gt&lt/printableName&gt
  &ltallowUnsecure&gt&lt/allowUnsecure&gt
  &lt/sapSncData&gt
  &ltsapUserGroupList&gt
  &ltgroup&gt
  &ltname&gt&lt/name&gt
  &lt/group&gt
  &ltgroup&gt
  &ltname&gt&lt/name&gt
  &lt/group&gt
  &lt/sapUserGroupList&gt
  &ltsapParameterList&gt
  &ltparameter&gt
  &ltparameterId&gt&lt/parameterId&gt
  &ltparameterValue&gt&lt/parameterValue&gt
  &lt/parameter&gt
  &ltparameter&gt
  &ltparameterId&gt&lt/parameterId&gt
  &ltparameterValue&gt&lt/parameterValue&gt
  &lt/parameter&gt
  &lt/sapParameterList&gt
  &ltsapUserEmailAddressList&gt
  &ltemail&gt
  &ltdefaultNumber&gt&lt/defaultNumber&gt
  &ltsmtpAddress&gt&lt/smtpAddress&gt
  &ltisHomeAddress&gt&lt/isHomeAddress&gt
  &ltsequenceNumber&gt&lt/sequenceNumber&gt
  &lt/email&gt
  &ltemail&gt
  &ltdefaultNumber&gt&lt/defaultNumber&gt
  &ltsmtpAddress&gt&lt/smtpAddress&gt
  &ltisHomeAddress&gt&lt/isHomeAddress&gt
  &ltsequenceNumber&gt&lt/sequenceNumber&gt
  &lt/email&gt
  &lt/sapUserEmailAddressList&gt
  &ltsapRoleList&gt
  &ltrole&gt
  &ltname&gt&lt/name&gt
  &ltvalidFromDate&gt&lt/validFromDate&gt
  &ltvalidToDate&gt&lt/validToDate&gt
  &lt/role&gt
  &ltrole&gt
  &ltname&gt&lt/name&gt
  &ltvalidFromDate&gt&lt/validFromDate&gt
  &ltvalidToDate&gt&lt/validToDate&gt
  &lt/role&gt
  &lt/sapRoleList&gt
  &ltsapProfileList&gt
  &ltprofile&gt
  &ltname&gt&lt/name&gt
  &lt/profile&gt
  &ltprofile&gt
  &ltname&gt&lt/name&gt
  &lt/profile&gt
  &lt/sapProfileList&gt
  &lt/User&gt
 

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

UserRegistryConnector()
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 user 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 Connector 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 user 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, 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

UserRegistryConnector

public UserRegistryConnector()

Construct the Connector.

Method Detail

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.

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 Connector method.

Specified by:

getLastWarningSet in interface AbapErrorCache

Returns:

a list of warning severity AbapErrorInfo. 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 list of error severity AbapErrorInfo. Minimum length will be zero.

initialize

public void initialize(java.lang.Object o)
                throws UserRegistryConnectorException,
                       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:

UserRegistryConnectorException - 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 UserRegistryConnectorException

Return the IBM Tivoli Directory Integrator Entry schema supported by this connector. The connector supports two attributes named "sapUserXml" and "sapUserName". sapUserXml is an XML string representing the attributes of a user to be operated on. sapUserName is a string representing a given user name in SAP. It is 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:

UserRegistryConnectorException - If an error occurs.

See Also:

Entry, Vector

putEntry

public void putEntry(Entry entry)
              throws ConnectorMethodException,
                     UserRegistryConnectorException

Called by IBM Tivoli Directory Integrator AL to add a new user 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 "sapUserXml". Its value must be an XML string conforming to the SAP User XML Schema. See user guide for more details.

Throws:

UserRegistryConnectorException - 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,
                        UserRegistryConnectorException

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 "sapUserXml". Its value must be an XML string conforming to the SAP User XML Schema. The XML must, at a minimum, contain the "sapUserName" element. Typically, the entry will be populated by the findEntry method, which is called by the AL before this method. See user guide for more details.

search - Passed through to XSL style sheet as an XSL param.

Throws:

UserRegistryConnectorException - 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), findEntry(com.ibm.di.server.SearchCriteria)

modEntry

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

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 "sapUserXml". Its value must be an XML string conforming to the SAP User XML Schema. The XML must, at a minimum, contain the "sapUserName" element. Typically, the entry will be populated by the findEntry method, which is called by the AL before this method. See user guide for more details.

search - Passed through to XSL style sheet as an XSL param.

Throws:

UserRegistryConnectorException - 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(com.ibm.di.server.SearchCriteria)

findEntry

public Entry findEntry(SearchCriteria search)
                throws ConnectorMethodException,
                       UserRegistryConnectorException

Called by IBM Tivoli Directory Integrator AL to find an existing user 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 name "sapUserName". Its value is the name of the user to be found.

Returns:

The entry populated with attribute "sapUserXml", or null if the user could not be found.

Throws:

UserRegistryConnectorException - 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,
                          UserRegistryConnectorException

Called by IBM Tivoli Directory Integrator AL when the connector operates in Iterator mode inside an assembly line. It finds all user names currently managed by the connected SAP R/3 instance. It stores all users names in a cached R3UsernameIterator following a RFC lookup to obtain the names.

Specified by:

selectEntries in interface ConnectorInterface

Overrides:

selectEntries in class Connector

Throws:

UserRegistryConnectorException - 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(), R3UsernameIterator

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 sapUserXml attribute. Its value is an XML string representing the user attributes. The result will be null when no more user entries 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.