This section describes the configuration and operation of the IBM TDI Connector for processing ALE IDOCs sent from an SAP ABAP Application Server or ERP system. The chapter contains the following sections:
In an SAP System the Application Link Enabling (ALE) is one of the core integration technologies. It involves the exchange of hierarchical data documents known as Intermediate Documents (IDOCs). There are two scenarios, inbound to SAP, and outbound from SAP. This release of the connector only integrates with IDOCs that are outbound from SAP, and inbound to IBM TDI. This document will use the term inbound with reference to inbound to IBM Tivoli Directory Integrator. The SAP System will always be the IDOC client with IBM TDI acting as the IDOC Server. The IDOC is sent to IBM TDI as an asynchronous event, and when received, IBM TDI pushes the IDOC data onto an AssemblyLine for processing as desired. As it is asynchronous communication, IBM TDI will not provide a response to the client SAP system. SAP TID management is used to ensure data consistency between the SAP system client and IBM TDI. Due to the asynchronous communication the Connector supports only Iterator mode.
When configuring ALE in an SAP System, the core task is to create what is called a distribution model. There are many pre-defined distribution models available as standard in an SAP system, but there is also the ability to create a customizable distribution model of our own. The core use of this connector is as an external application that acts as a logical system within the chosen SAP distribution model. The examples provided in this chapter will define integration into a custom SAP HR distribution model, and the pre-defined SAP Central User Management (CUA) distribution model. Of course the connector could be used for integration into any of the other SAP distribution models to access the master data for other SAP modules such as SAP FI/CO or SAP PP. For detailed information on SAP modules visit the SAP help site at http://help.sap.com. Almost any SAP master data business object with an IDOC interface can be exchanged this way.
Central to creating or configuring an SPA distribution model are the IDOC message types we want to support. What the connector provides is an XML version of the IDOC, which must be parsed accordingly. To facilitate parsing of the IDOC XML data the connector has been enabled to make use of the IBM TDI XML parsers. You have the choice of the DOM Parser, the SAX Parser or the XSLT Parser. Using these will enable you to extract the required data from the IDOC for you business purpose. For example you may wish to extract particular infotypes from the SAP HR IDOC message type HRMD_A to forward on to IBM Tivoli Identity Manager for automated provisioning purposes.
The figure below illustrates the interaction with the SAP System IDOC client and the IBM TDI IDOC server.
Interaction with the SAP System IDOC client and the IBM TDI IDOC server
The SAP ALE IDOC Connector for SAP ABAP Application Server is part of the IBM TDI 7.1 installation package. However, in order for the Connector to function correctly, some SAP class libraries need to be obtained and installed, alongside the sapjco.jar file as outlined in the installation instructions for the entire Component Suite:
The SAP ALE IDOC Connector for SAP ABAP Application Server may be added directly into an assembly line. The following section lists the configuration parameters the connector.
"jco.server.trace=1 jco.server.sysnr=00"
"jco.client.trace=1 jco.client.use_sapgui=1"The following is a list of optional SAP Java Connector parameters that are accessible.
Alias user name [jco.client.alias_user]
SAP message server [jco.client.mshost]
RFC trace [jco.client.trace]
Initial codepage in SAP notation [jco.client.codepage]
Secure network connection (SNC) mode, 0 (off) or 1 (on) [jco.client.snc_mode]
SNC partner, for example, p:CN=R3, O=XYZ-INC, C=EN [jco.client.snc_partnername]
SNC level of security, 1 to 9 [jco.client.snc_qop]
SNC name. Overrides default SNC partner [jco.client.snc_myname]
Path to library, which provides SNC service [jco.client.snc_lib]
SAP R/3 name [jco.client.r3name]
Group of SAP application servers [jco.client.group]
Program ID of external server program [jco.client.tpname]
Host of external server program [jco.client.tphost]
Type of remote host 2 = R/2, 3 = R/3, E = External [jco.client.type]
Enable ABAP debugging 0 or 1 [jco.client.abap_debug]
Use remote SAP graphical user interface (0/1/2) [jco.client.use_sapgui]
Get/Don't get a SSO ticket after logon (1 or 0) [jco.client.getsso2]
Use the specified SAP Cookie Version 2 as logon ticket [jco.client.mysapsso2]
Use the specified X509 certificate as logon ticket [jco.client.x509cert]
Enable/Disable logon check at open time, 1 (enable) or 0 (disable) [jco.client.lcheck]
String defined for SAPLOGON on 32-bit Windows [jco.client.saplogon_id]
Data for external authentication (PAS) [jco.client.extiddata]
Type of external authentication (PAS) [jco.client.extidtype]
Idle timeout (in seconds) for the connection after which it will be closed by R/3.
Only positive Enable (1) or Disable (0) dsr support [jco.client.dsr]
The processing performed for RFM calls is merely to provide the RFM as an XML valued attribute. The IDOC Server does not currently attempt to populate the export and table arguments of the RFM call. If required this can be provided under an enhancement of the Connector. To do this contact IBM Support. Only RFM calls that form part of an ALE distribution models internal process should be considered.
This section describes details on using the Connector in the supported Iterator mode. Also described is the IBM TDI schema supported by the Connector.
The schema for the Connector is centred on providing an AssemblyLine with Entries, where each represents and individual IDOC. An IDOC itself contains 3 sections of data. These are Control Data, Segment Data, and Status Data. The simplest and most effective way of representing this data in IBM TDI is an XML format, which can be easily dissected for the required data. As the control data is readily accessible, and can provide useful standalone information, this data is also available as individual attributes. The configuration parameter "IDOC As XML Only?" is used to enable or disable the production of the control data as stand alone attributes.
As the Connector is also able to accept Remote Function Module requests, there is a requirement to represent the data in one or more attributes. Currently the content of an RFM will be available as a single XML valued attribute. The configuration parameter "Process SAP RFM Requests?" is used to enable or disable the production of the RFM XML valued attribute.
The table below defines the schema available to this Connector.
Attribute Name | Attribute Description | Attribute Syntax |
---|---|---|
idoc.tid | Input schema attribute whose value is the associated TID value provided by the SAP System Client. | java.lang.string |
idoc.xml | Input schema attribute whose value is the complete IDOC in XML format. | java.lang.string |
idoc.segments.xml | Input schema attribute whose value is the complete Segment hierarchy in XML format. No control attribute values are contained in this XML. | java.lang.string |
idoc.ctrl.ArchiveKey | Input schema attribute whose value represents the IDOC control data archive key (the value of the field "ARCKEY"). | java.lang.string |
idoc.ctrl.Client | Input schema attribute whose value represents the IDOC control data client (the value of the field "MANDT"). | java.lang.string |
idoc.ctrl.CreationDate | Input schema attribute whose value represents the IDOC control data creation date (the value of the field "CREDAT"). | java.lang.string |
idoc.ctrl.CreationTime | Input schema attribute whose value represents the IDOC control data creation time (the value of the field "CRETIM"). | java.lang.string |
idoc.ctrl.Direction | Input schema attribute whose value represents the IDOC control data direction (the value of the field "DIRECT"). | java.lang.string |
idoc.ctrl.EDIMessage | Input schema attribute whose value represents the IDOC control data EDI message (the value of the field "REFMES"). | java.lang.string |
idoc.ctrl.EDIMessageGroup | Input schema attribute whose value represents the IDOC control data EDI message group (the value of the field "REFGRP"). | java.lang.string |
idoc.ctrl.EDIMessageType | Input schema attribute whose value represents the IDOC control data EDI message type (the value of the field "STDMES"). | java.lang.string |
idoc.ctrl.EDIStandardFlag | Input schema attribute whose value represents the IDOC control data EDI standard flag (the value of the field "STD"). | java.lang.string |
idoc.ctrl.EDIStandardVersion | Input schema attribute whose value represents the IDOC control data EDI standard version (the value of the field "STDVRS"). | java.lang.string |
idoc.ctrl.EDITransmissionFile | Input schema attribute whose value represents the IDOC control data EDI transmission file (the value of the field "REFINT"). | java.lang.string |
idoc.ctrl.ExpressFlag | Input schema attribute whose value represents the IDOC control data express flag (the value of the field "EXPRSS"). | java.lang.string |
idoc.ctrl.IDocCompoundType | Input schema attribute whose value represents the IDOC control data IDOC compound type (the value of the field "DOCTYP"). | java.lang.string |
idoc.ctrl.IDocNumber | Input schema attribute whose value represents the IDOC control data IDOC number (the value of the field "DOCNUM"). | java.lang.string |
idoc.ctrl.IDocSAPRelease | Input schema attribute whose value represents the IDOC control data IDOC SAP release (the value of the field "DOCREL"). | java.lang.string |
idoc.ctrl.IDocType | Input schema attribute whose value represents the IDOC control data IDOC type (the value of the field "IDOCTYP"). | java.lang.string |
idoc.ctrl.IDocTypeExtension | Input schema attribute who's value represents the IDOC control data IDOC type extension that is also known as CIM type or customer extension type (the value of the field "CIMTYP"); | java.lang.string |
idoc.ctrl.MessageCode | Input schema attribute whose value represents the IDOC control data message code (the value of the field "MESCOD"). | java.lang.string |
idoc.ctrl.MessageFunction | Input schema attribute whose value represents the IDOC control data message function (the value of the field "MESFCT"). | java.lang.string |
idoc.ctrl.MessageType | Input schema attribute whose value represents the IDOC control data message type (the value of the field "MESTYP"). | java.lang.string |
idoc.ctrl.OutputMode | Input schema attribute whose value represents the IDOC control data output mode (the value of the field "OUTMOD"). | java.lang.string |
idoc.ctrl.RecipientAddress | Input schema attribute whose value represents the IDOC control data recipient address (the value of the field "RCVSAD"). | java.lang.string |
idoc.ctrl.RecipientLogicalAddress | Input schema attribute whose value represents the IDOC control data logical recipient address (the value of the field "RCVLAD"). | java.lang.string |
idoc.ctrl.RecipientPartnerFunction | Input schema attribute whose value represents the IDOC control data recipient partner function (the value of the field "RCVPFC"). | java.lang.string |
idoc.ctrl.RecipientPartnerNumber | Input schema attribute whose value represents the IDOC control data recipient partner number (the value of the field "RCVPRN"). | java.lang.string |
idoc.ctrl.RecipientPartnerType | Input schema attribute whose value represents the IDOC control data recipient partner type (the value of the field "RCVPRT"). | java.lang.string |
idoc.ctrl.RecipientPort | Input schema attribute whose value represents the IDOC control data recipient port (the value of the field "RCVPOR"). | java.lang.string |
idoc.ctrl.SenderAddress | Input schema attribute whose value represents the IDOC control data sender address (the value of the field "SNDSAD"). | java.lang.string |
idoc.ctrl.SenderLogicalAddress | Input schema attribute whose value represents the IDOC control data logical sender address (the value of the field "SNDLAD"). | java.lang.string |
idoc.ctrl.SenderPartnerFunction | Input schema attribute whose value represents the IDOC control data sender partner function (the value of the field "SNDPFC"). | java.lang.string |
idoc.ctrl.SenderPartnerNumber | Input schema attribute whose value represents the IDOC control data sender partner number (the value of the field "SNDPRN"). | java.lang.string |
idoc.ctrl.SenderPartnerType | Input schema attribute whose value represents the IDOC control data sender partner type (the value of the field "SNDPRT"). | java.lang.string |
idoc.ctrl.SenderPort | Input schema attribute whose value represents the IDOC control data Returns the sender port (the value of the field "SNDPOR"). | java.lang.string |
idoc.ctrl.Serialization | Input schema attribute whose value represents the IDOC control data serialization (the value of the field "SERIAL"). | java.lang.string |
idoc.ctrl.Status | Input schema attribute whose value represents the IDOC control data status (the value of the field "STATUS"). | java.lang.string |
idoc.ctrl.TableStructureName | Output schema attribute whose value represents the IDOC control data table structure name (the value of the field "TABNAM"). | java.lang.string |
idoc.ctrl.TestFlag | Input schema attribute whose value represents the IDOC control data test flag (the value of the field "TEST"). | java.lang.string |
rfm.xml | Input schema attribute whose value represents the complete content of an RMF request in XML format. | java.lang.string |
Attributes of type java.lang.String can be of arbitrary length.
The main mode of operation for the connector is the production of the XML valued attributes that represent the complete content of an IDOC, or RFM. As a result the best way to handle this data is with one of the available IBM TDI XML Parsers attached to the Connector. Due to the nested nature of the resulting XML, the DOM parser is not recommended, but still can be used. The recommended parsers are the SAX Parser or the XSLT Parser depending on the type of SAP ALE distribution model the Connector is to integrate with. If the Connector has to handle multiple IDOC message types, or is configured to process RFM requests, then the SAX Parser is recommended. This is because we will have different XML schemas for the different IDOC message types, and the RFM XML. The SAX Parser is the only IBM TDI parser that can handle XML values with different XML schemas. You do this by not configuring the SAX Parser to have a specific value for it's "Group" configuration parameter. This has the effect of not having to define a particular root element. If you are certain that the Connector will process only one type of IDOC, then we can use the XSLT Parser, which allows for a more complete Connector Entry to Work Entry attribute mapping. For example if the Connector was configured to be the recipient of SAP HR Master Data, then you would only ever expect to see IDOCs of the message type HRMD_A. At the time this connector was developed the latest version of this message type was HRMD_A06. We could then use and XSL like the following to parse the IDOCs contents for the required data.
<XSL:stylesheet xmlns:XSL="http://www.w3.org/1999/XSL/Transform" version="1.0"> <XSL:output method="XML" indent="yes" /> <XSL:template match="HRMD_A06"> <DocRoot> <Entry> <XSL:apply-templates select="./IDOC"/> </Entry> </DocRoot> </XSL:template> <XSL:template match="IDOC"> <XSL:apply-templates select="./EDI_DC40"/> <XSL:apply-templates select="./E1PLOGI"/> </XSL:template> <XSL:template match="EDI_DC40"> <Attribute name="IDOC_CTRL_DOCNUM"> <XSL:for-each select="DOCNUM"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="IDOC_CTRL_MANDT"> <XSL:for-each select="MANDT"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="IDOC_CTRL_DOCREL"> <XSL:for-each select="DOCREL"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="IDOC_CTRL_IDOCTYP"> <XSL:for-each select="IDOCTYP"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="IDOC_CTRL_SNDPOR"> <XSL:for-each select="SNDPOR"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="IDOC_CTRL_RCVPOR"> <XSL:for-each select="RCVPOR"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> <XSL:template match="E1PLOGI"> <XSL:apply-templates select="./E1PITYP"/> </XSL:template> <XSL:template match="E1PITYP"> <XSL:apply-templates select="./E1P0002"/> <XSL:for-each select="E1P0105"> <Attribute name="PR_COMM_SUBTY"> <XSL:for-each select="SUBTY"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="PR_COMM_USRID"> <XSL:for-each select="USRID"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="PR_COMM_USRID_LONG"> <XSL:for-each select="USRID_LONG"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:for-each> </XSL:template> <XSL:template match="E1P0002"> <Attribute name="PR_PERNR"> <XSL:for-each select="PERNR"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="PR_LASTNAME"> <XSL:for-each select="NACHN"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="PR_FIRSTNAME"> <XSL:for-each select="VORNA"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="PR_BIRTHDATE"> <XSL:for-each select="GBDAT"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> </XSL:stylesheet>
If the IDOC message type was always going to be the USERCLONE message type, then you could use XSL like the following to get the required attribute mappings.
<XSL:stylesheet xmlns:XSL="http://www.w3.org/1999/XSL/Transform" version="1.0"> <XSL:output method="XML" indent="yes" /> <XSL:template match="USERCLONE05"> <DocRoot> <Entry> <XSL:apply-templates select="./IDOC"/> </Entry> </DocRoot> </XSL:template> <XSL:template match="IDOC"> <XSL:apply-templates select="./EDI_DC40"/> <XSL:apply-templates select="./E1BPBNAME"/> <XSL:apply-templates select="./E1BPLOGOND"/> <XSL:apply-templates select="./E1BPADDR3"/> <XSL:apply-templates select="./E1BPLOGOND"/> <XSL:apply-templates select="./E1BPUSCOMP"/> </XSL:template> <XSL:template match="EDI_DC40"> <Attribute name="TDI_DOCNUM"> <XSL:for-each select="DOCNUM"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_MANDT"> <XSL:for-each select="MANDT"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_DOCREL"> <XSL:for-each select="DOCREL"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_IDOCTYP"> <XSL:for-each select="IDOCTYP"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_USERCLONE"> <XSL:for-each select="USERCLONE"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_SNDPOR"> <XSL:for-each select="SNDPOR"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_RCVPOR"> <XSL:for-each select="RCVPOR"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> <XSL:template match="E1BPBNAME"> <Attribute name="TDI_BAPIBNAME"> <XSL:for-each select="BAPIBNAME"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> <XSL:template match="E1BPLOGOND"> <Attribute name="TDI_CLASS"> <XSL:for-each select="CLASS"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_TZONE"> <XSL:for-each select="TZONE"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> <XSL:template match="E1BPADDR3"> <Attribute name="TDI_FIRSTNAME"> <XSL:for-each select="FIRSTNAME"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <Attribute name="TDI_LASTNAME"> <XSL:for-each select="LASTNAME"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> <XSL:apply-templates select="./E1BPADDR1"/> </XSL:template> <XSL:template match="E1BPADDR1"> <Attribute name="TDI_E_MAIL"> <XSL:for-each select="E_MAIL"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> <XSL:template match="E1BPUSCOMP"> <Attribute name="TDI_COMPANY"> <XSL:for-each select="COMPANY"> <Value> <XSL:value-of select="." /> </Value> </XSL:for-each> </Attribute> </XSL:template> </XSL:stylesheet>
To enable the connector to be part of an SAP ALE distribution model the Connector must be setup as a logical system on the SAP system. To do this, two actions are required.
Once the logical system is in place we can pretty much use it as you would any other logical system in an SAP ALE distribution model. The Connector has been tested as part of a SAP HR Master Data distribution model, and as part of the pre-defined SAP CUA distribution model. If we run into other issues using other SAP ALE distribution models please contact IBM Support.