Directory Integrator, Version 7.1.1
This section describes the configuration and operation of the IBM® Tivoli® Directory Integrator SAP ABAP Application Server Business Object Repository Connector.
This chapter contains the following sections:
The SAP Human Resources modules include a large range of business features. The major feature areas address the business needs of payroll, personnel time management, and general personnel master data management.
From a data perspective, the backbone of the SAP HR system is the infotype. Infotypes are a logical grouping of related attributes. SAP defines a large set of default infotypes, which are grouped and identified in SAP using number ranges. The table below shows the ranges:
| Number Range | HR Submodule |
|---|---|
| 0000 to 0999 | HR Master Data |
| 1000 to 1999 | Personnel Planning |
| 2000 to 2999 | Time Management |
| 4000 to 4999 | Recruitment |
| 9000 to 9999 | Custom extensions |
Since there are such a large number of infotypes, it is quite difficult to design a single Tivoli Directory Integrator Connector to cover and suit all SAP HR integration requirements. Fortunately, SAP supports access to its HR data repositories via Business APIs (BAPI) that are attached to objects in the Business Object Repository (BOR). As a result, a generic BOR Connector has been designed and implemented. This Connector can invoke any method of any BOR object. The Connector projects an XML representation of the data managed by the given BOR object. The Connector requires the configuration of a set of XSL style sheets, and specification of the class identification name for the given BOR object (in fact, the XSL style sheets define the XML data representation).
The figure below illustrates the component design of the Connector.
Tivoli Directory Integrator supplies an example set of XSL style sheets that enable the Connector to manage HR Personal Data (Infotype 0002). The style sheets have been setup to invoke the BAPI RFC methods of the PERSDATA BOR object. The Connector uses the generic RFC invocation feature of the Tivoli Directory Integrator Function Component for SAP ABAP Application Server.
The key features and benefits of the Connector are:
The Connector supports the following standard Tivoli Directory Integrator Connector modes, but relies on the standard BAPI methods to deliver the functionality of each mode:
The table below gives an example of Connector mode to BAPI method mappings
| Connector Mode | BAPI Method |
|---|---|
| Add | Create, CreateFromData |
| Update | Change |
| Delete | Delete |
| Lookup | Get, GetDetail |
| Iterator | GetList, Get, GetDetailedList |
Key fields of BOR objects are given special treatment by the Connector. This is reflected in the XML representation of BOR object data.
While it is possible to define alternate XSL style sheets to process request and response XML, the style sheets must support an element named sapBorObjIdentifier. This element is processed by the Java code of the Connector when returning entries in Lookup and Iterator modes. The sapBorObjIdentifier may appear anywhere within the XML. The contents of the element are elements whose tag names match the names of the key fields of the given BOR object.
The general form of the HR Personal Data XML is shown below.
<sapPersonalData>
<sapBorObjIdentifier>
<EmployeeNumber>00000001</EmployeeNumber>
<SubType />
<ObjectID />
<LockIndicator />
<ValidityEnd>99991231</ValidityEnd>
<ValidityBegin>19740320</ValidityBegin>
<RecordNumber>000</RecordNumber>
</sapBorObjIdentifier>
<personalDataDetail>
<title>1</title>
<firstname></firstname>
<lastname></lastname>
<nameAtBirth />
<knownAs></knownAs>
<surnamePrefix />
<gender></gender>
<dateOfBirth></dateOfBirth>
<birthPlace />
<stateOfBirth />
<countryOfBirth />
<maritalStatus></maritalStatus>
<numberOfChildren></numberOfChildren>
<religion />
<language></language>
<languageCode></languageCode>
<nationality></nationality>
<idNumber />
</personalDataDetail>
</sapPersonalData>The SAP ABAP Application Server Business Object Repository Connector supports the Skip Lookup general option in Update or Delete mode. When it is selected, no search is performed prior to actual update and delete operations.
For this to function, for HR Personal Data (infotype 0002), the following attributes must be defined in the Link Criteria:
The BOR Connector for SAP ABAP Application Server (SAP ABAP AS) may be added directly into an assembly line. The following section lists the configuration parameters that are available for SAP client connections and XSL style sheet behavior. Runtime names are shown in parentheses.
"gwserv=sapgw00 use_sapgui=1"Here is a list of optional SAP Java Connector parameters that are accessible.
ibmdi.SapR3RfcFCThis section describes the details of using the Connector in each of the supported Tivoli Directory Integrator Connector modes. The section also describes the Tivoli Directory Integrator Entry schema supported by the Connector.
The BOR Connector supports one native attribute named sapXml. The value of sapXml is an XML string representing the attributes of a BOR object. Other attributes reflect the given BOR object key field names. They are supported to allow the definition of IBM Tivoli Directory Integrator Link Criteria when the Connector is deployed in Lookup, Delete, or Update modes.
The schema is available via the query schema feature in the IBM Tivoli Directory Integrator configuration tool. The attribute schema is described below.
| Attribute Name | Type | Description |
|---|---|---|
| sapXml | java.lang.String | A string representing the attributes of an SAP BOR
Object.
This attribute and value must be present on the Output Map when the Connector is deployed in Add Only and Update modes. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| EmployeeNumber | java.lang.String | Personal Data Infotype 0002 specific.
The 8 digit employee number. This attribute and value must be present on the Link Criteria when the Connector is deployed in Lookup, Update and Delete modes. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| Subtype | java.lang.String | Personal Data Infotype 0002 specific.
The 4 character personal data subtype. This attribute and value must be present on the Link Criteria when the Connector is deployed in Lookup, Update and Delete modes. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| ObjectID | java.lang.String | Personal Data Infotype 0002 specific.
The 2 character object ID for infotypes where all other key fields are the same. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| LockIndicator | java.lang.String | Personal Data Infotype 0002 specific.
The 1 character flag indicating if the master data record is locked in SAP. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| ValidityEnd | java.lang.String | Personal Data Infotype 0002 specific.
8 digit date value (YYYYMMDD). This attribute and value must be present on the Link Criteria when the Connector is deployed in Lookup, Update and Delete modes. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| ValidityBegin | java.lang.String | Personal Data Infotype 0002 specific.
8 digit date value (YYYYMMDD). This attribute and value must be present on the Link Criteria when the Connector is deployed in Lookup, Update and Delete modes. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
| RecordNumber | java.lang.String | Personal Data Infotype 0002 specific.
2 digit value. This attribute is available on the Input Map when the Connector is deployed in Lookup and Iterator modes. |
When deployed in Add Only mode, the Connector is able to create a new object in the SAP database. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. The Output Map must define a mapping for the sapXml Connector attribute. The value of this attribute represents the details of the object to be added to SAP. The value will be applied to each configured XSLT file in the order defined. The XSLT transforms produce separate RFC XML requests to be executed by the RFC Function Component, which is managed internally by the Connector.
The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.
For HR Personal Data (infotype 0002), a valid employee number must exist. The general form of the XML is shown below. The mandatory elements are EmployeeNumber, ValidityBegin, and ValidityEnd.
<sapPersonalData>
<sapBorObjIdentifier>
<EmployeeNumber>00000001</EmployeeNumber>
<SubType />
<ObjectID />
<LockIndicator />
<ValidityEnd>99991231</ValidityEnd>
<ValidityBegin>19740320</ValidityBegin>
<RecordNumber>000</RecordNumber>
</sapBorObjIdentifier>
<personalDataDetail>
<title></title>
<firstname></firstname>
<lastname></lastname>
<nameAtBirth />
<knownAs>Torpedo</knownAs>
<surnamePrefix />
<gender>1</gender>
<dateOfBirth></dateOfBirth>
<birthPlace />
<stateOfBirth />
<countryOfBirth />
<maritalStatus></maritalStatus>
<numberOfChildren></numberOfChildren>
<religion />
<language></language>
<languageCode></languageCode>
<nationality></nationality>
<idNumber />
</personalDataDetail>
</sapPersonalData>When deployed in Update mode, the Connector is able to modify an existing object in the SAP database. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. The Output Map must define a mapping for the sapXml Connector attribute. The value of this attribute represents the details of the user to be changed in SAP. The value will be applied to each configured XSLT file in the order defined. The XSLT transforms produce separate RFC XML requests to be executed by the RFC Function Component, which is managed internally by the Connector.
Additionally, some of the key fields of the BOR object are needed for the Link Criteria of the Connector. The Link Criteria is required by the AssemblyLine, since the AssemblyLine will invoke the Connector's findEntry() method to verify the existence of the given object. All parameters defined in the Link Criteria are passed as XSLT style sheet parameters. If duplicate Link Criteria names are supplied, the Connector will use the last value supplied.
The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.
For HR Personal Data (infotype 0002), the following attributes must be defined in the Link Criteria:
Since these attributes are passed as parameters to the XSL style sheets, they are not required in the XML. The general form of the XML is shown below.
<sapPersonalData>
<sapBorObjIdentifier>
<SubType />
<ObjectID />
<LockIndicator />
<RecordNumber>000</RecordNumber>
</sapBorObjIdentifier>
<personalDataDetail>
<title></title>
<firstname></firstname>
<lastname></lastname>
<nameAtBirth />
<knownAs>Torpedo</knownAs>
<surnamePrefix />
<gender></gender>
<dateOfBirth></dateOfBirth>
<birthPlace />
<stateOfBirth />
<countryOfBirth />
<maritalStatus></maritalStatus>
<numberOfChildren></numberOfChildren>
<religion />
<language></language>
<languageCode></languageCode>
<nationality></nationality>
<idNumber />
</personalDataDetail>
</sapPersonalData>When deployed in Delete mode, the Connector is able to delete an existing object from the SAP database. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. In Delete mode, the Connector relies solely on the Link Criteria. All parameters defined in the Link Criteria are passed as XSLT style sheet parameters. If duplicate Link Criteria names are supplied, the Connector will use the last value supplied.
The Connector does not support duplicate or multiple entries. Only one entry should be supplied to the Connector at a time.
For HR Personal Data (infotype 0002), the following Attributes must be defined in the Link Criteria:
When deployed in Lookup mode, the Connector is able to obtain all details of a given SAP object. The Connector should be added to the Flow section of a Tivoli Directory Integrator AssemblyLine. Connector key field attributes should be defined in the Link Criteria of the Connector. If duplicate Link Criteria names are supplied, the Connector will use the last value supplied. The Connector will populate the XML string value of the attribute sapXml and make it available to the AssemblyLine in the Connector's Input Map. The key field names and values are also made available to the Input Map.
The Connector's findEntry() method is the main code executed. It uses the result of the XSLT transform configured in Lookup Mode Pre StyleSheet to execute an RFC and obtain all details for the given user. The result of the RFC is then transformed using the XSLT transform configured in Lookup Mode Post StyleSheet.
The Connector does not support duplicate or multiple entries. The Connector will return only entry at a time.
For HR Personal Data (infotype 0002), the following Attributes must be defined in the Link Criteria:
When deployed in Iterator mode, the Connector is able to retrieve the details of each object in the SAP database, in turn, and make those details available to the AssemblyLine. The XSLT style sheets for Select Entries Pre StyleSheet, Select Entries Post StyleSheet, Iterator Mode Pre StyleSheet, and Iterator Mode Post StyleSheet must be configured.
When deployed in this mode, the Tivoli Directory Integrator AssemblyLine will first call the Connector's selectEntries() method to obtain and cache a list of all key field names and values (for the given BOR object) in the SAP database. The AssemblyLine will then call the Connector's getNextEntry() method. This method will maintain a pointer to the current key field cached in the list. The method will use the key field information to call an RFC to obtain all details for the object. The result of the RFC are formatted by an XSLT transform and set as the value of sapXml and returned by the Connector. The key field names and values are also made available to the Input Map.
When the Connector is deployed in a mode that results in write operations with SAP (Add Only, Update, Delete), it is possible for operations to be partially complete. This can occur if multiple XSL style sheets, which generate RFC requests, are required to complete the operation. If one of the earlier RFC requests fails, then RFC requests executed subsequently may fail as a result.
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 designed to make the RFC return status available to the AssemblyLine. 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. For specific details, refer to the Javadoc contained in the distribution package.
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());
}
}