SDN Community Contribution (This is not an official SAP document.) Disclaimer & Liability Notice This document may discuss sample coding or other information that does not include SAP official interfaces and therefore is not supported by SAP. Changes made based on this information are not supported and can be overwritten during an upgrade. SAP will not be held liable for any damages caused by using or misusing the information, code or methods suggested in this document, and anyone using these methods does so at his/her own risk. SAP offers no guarantees and assumes no responsibility or liability of any type with respect to the content of this technical article or code sample, including any liability resulting from incompatibility between the content within this document and the materials and services offered by SAP. You agree that you will not hold, or seek to hold, SAP responsible or liable with respect to the content of this document. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 1
Applies To: The document applies to SAP Exchange Infrastructure 3.0. Summary In a typical implementation of SAP XI, a large chunk of all the scenarios handled are the ones where the sender adapter is a File adapter. The file coming into the SAP XI system needs to be validated on multiple counts like completeness of file, existence of mandatory records, and proper sequence of records to name a few. These validations can be categorized into different classes based on the severity of error identified and the incoming file needs to be handled differently for failure on different classes of validations. Also, the proper authorities need to be alerted of these errors through the proper channels. This document deals with a sample methodology adopted for incorporating the above mentioned functionality in an XI interface. The document will describe the following main features of the functionality developed: Reading the entire file via a file adapter and performing validations on the payload Recording the errors occurring and inserting them in the payload Segregating the valid records from erroneous records in the payload Splitting the message into two valid and invalid and process them accordingly By: Aniket Tare Company: Wipro Technologies Date: 24 August 2005 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 2
Table of Content Applies To:...2 Summary...2 Table of Content...3 About This Tutorial...4 What is the Scenario?...4 1.1 Source File Details...4 1.2 IDoc Structure...4 Define the Problem...5 The Solution Explained...6 3.1 File Content Conversion...7 3.2 C1 Validations Implementation...8 3.3.1 The Java Mapping Program (Flat Source to Valid and Invalid Record Sets)...10 3.3.2 The Direct Mapping Program...12 3.3.3 The Integration Process (Sending the Two Messages to Respective Receivers)...14 Disclaimer & Liability Notice...15 Author Bio...15 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 3
About This Tutorial What is the Scenario? A rather simple scenario is selected to demo this solution. Following are the main actions: A file needs to be polled via the file adapter into SAP XI and validations need to be carried out on the records Valid and invalid records need to be segregated Valid records are posted into the IS-Utilities system as IDocs Invalid ones are reported via e-mail to the administrator. 1.1 Source File Details Below is content of a sample source file. A typical file consists of one A00 record, one Z99 record, and multiple M03 records. "A00",399,"MBR",20050405,002326,2700 "M03","0015893088",001","F",20050331,"00785815",3315570905,,"N",1,"CYLM","N"," 8345",4,"",,"",,,"","","U","U","U","N",,,,,,"I",1.02264,,1.0,0,0,46620402," 77223243","N",0,140,"KITCHEN U/SINK",,"U6","","CR" "Z99",2 A00 is the key value for the header record. M03 is the key value for the transaction record. Z99 is the key value for the trailer record. Each valid M03 record corresponds to an IDoc to be posted into the SAP IS-Utilities system. The IDoc structure is as given below. 1.2 IDoc Structure IDOC A00 M03 Thus, for each M03 record, the A00 record needs to be repeated and an IDoc containing both the records with the hierarchy as shown above needs to be posted. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 4
Define the Problem The data in the incoming file needs to be validated. The validations that need to be carried out on the file have been classified into three types. Details as follows: Validation Class Validation Details Action if Validations Fails Class 1 (C1) Checks that a file contains a header and trailer record. Checks that the header record contains the correct number of data items. Checks that mandatory data items within the header record are populated. Checks that all populated data items in the header (mandatory or optional) are of the correct size, type, and format. Checks for duplicate files being received. The entire file will be rejected. Class 2 (C2) Checks that the file contains a body. Checks that the body of the file is made up from valid groups applicable to the flow type. Checks that the groups appear in the correct sequence. Checks that mandatory groups are present. Checks that correct number of data items are present regardless of optimality or format. The record failing the validation will be rejected. Class 3 (C3) Checks that mandatory data items within the groups are populated. Checks that all populated data items (mandatory or optional) in each group are of the correct size, type and format. The record failing the validation will be rejected. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 5
The Solution Explained The solution consists of all the basic components of a File-to-IDoc scenario plus a few extra. In this document only the extra components will be explained, however before we get to the details of those components, let us understand the process flow. The components to be discussed are: File content conversion to pick up the entire record as a field. Module processor for implementing C1 validations. Java mapping program, direct mapping program and integration process for C2 and C3 validations implementation. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 6
3.1 File Content Conversion In the file content conversion we pick up each record of the file as one field. We do not mention the key field values for each record. The key field value mentioned here will be * (see picture below). The reason we pick up the entire record as a field is that we need to ensure that the file content conversion does not fail due to an incorrect number of fields in a record. In fact this is a validation that we need to perform and hence cannot afford not picking up the file on this account! 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 7
3.2 C1 Validations Implementation The C1 validations will be performed inside an EJB developed as a file adapter module. This module will be called before the standard CallSapAdapter module. The input to this module will be the output of file the content conversion, i.e. the flat XML file containing rowwise data. The module will be responsible for identifying the header and trailer records and performing the said C1 validations on them. (Note: Details of how these validations are performed is not in scope of this document.) If all the C1 validations are successful, the module will produce exactly the same output as the input XML document. If C1 validations fail, the module will modify the payload and insert the following in the XML payload: A tag consisting of an error flag. A tag consisting of the erroneous file name. Multiple tags each consisting of an error message. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 8
The output xml in case of C1 validations failure looks as below. In case C1 validations fail, the error flag set by the module is read in a condition in the receiver determination step and the message is sent to a receiver that will handle the error message. This receiver consisting of a communication channel using mail adapter then sends this message via e-mail to the administrator. The mail content consists of the erroneous payload, erroneous file name and the error records. The processing is stopped here. This way, through the use of module adapter and condition in receiver determination, we ensure that a file failing in C1 validations is rejected then and there and is not sent for further processing. 3.3 C2 and C3 Validations Implementation C2 and C3 validations are record and field level validations respectively. Unlike in case of C1 validations where we reject the entire file if the validations fail, in case of failure of C2 and C3 validations we only reject that particular record. Consequently, the output of C2 and C3 validations are two sets of records valid and invalid. Hence the C2 and C3 validations implementation needs to take care of: Performing C2 and C3 validations on the flat source XML document. Segregating the valid and invalid records in two record sets in an output message (master output). Creating two output messages (valid and invalid) from the master output message. The components that have been implemented in order to achieve the above requirements are described below. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 9
3.3.1 The Java Mapping Program (Flat Source to Valid and Invalid Record Sets) Instinctively (I believe), the best place to perform record level validations is a mapping program. Hence the C2 and C3 validations are performed in a Java mapping program. The mapping program takes as input the flat XML payload that is the output of C1 validations module. The mapping program is responsible for performing the C2 and C3 validations on each of the transaction records and segregates the valid records from the invalid records. (Note: Details of validations is not in the scope of this document.) The output of the mapping program is two separate record sets, one containing correct messages and the other containing incorrect messages. Source message: Java mapping program: Target message: 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 10
The structure of message for valid records is exactly identical to the IDoc structure. IDOC A00 M03 The structure of message for invalid records is as below. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 11
3.3.2 The Direct Mapping Program (Message Containing Valid and Invalid Record Sets to Individual Valid and Invalid Messages) After obtaining valid and invalid sets of records in a single message, a direct mapping program with two target messages (structures identical to valid and invalid record structures) creates two separate messages. Source message: The source message in the test environment of the mapping program is shown below: 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 12
Direct mapping program: Target message: The output of the mapping program in the test environment is shown below. Note: MT_REC_GEN in the above figure denotes the incorrect records. These are mapped to the Content node of the standard XSD of the mail adapter and a mail is sent to the administrator. (Note: Details of that mapping are not mentioned as part of the document.) 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 13
3.3.3 The Integration Process (Sending the Two Messages to Respective Receivers) The integration process receives the master output message. It then splits the message into two and sends each of the valid and invalid messages to the respective receivers. Receive step: Transformation step 1: In this step the master output is split into two messages Message_Correct and Message_Incorrect (direct mapping program). Fork: Duplicates the messages into two. Transformation step 2: refers to the mapping program that maps the records in Message_Incorrect to Content node as the standard XSD used for mail adapters. Thus the records appear as content of mail to the administrator. Send step 1: Sends the incorrect records as content of a mail to the administrator. Send step 2: Sends the correct records as idocs to the SAP ISU system. The valid records (records passing C2 and C3 validations) are posted into the SAP IS-U system as IDocs and the invalid records are sent across via mail to the administrator. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 14
Disclaimer & Liability Notice This document may discuss sample coding, which does not include official interfaces and therefore is not supported. Changes made based on this information are not supported and can be overwritten during an upgrade. SAP will not be held liable for any damages caused by using or misusing of the code and methods suggested here, and anyone using these methods, is doing it under his/her own responsibility. SAP offers no guarantees and assumes no responsibility or liability of any type with respect to the content of the technical article, including any liability resulting from incompatibility between the content of the technical article and the materials and services offered by SAP. You agree that you will not hold SAP responsible or liable with respect to the content of the Technical Article or seek to do so. Author Bio Aniket Tare is an SAP NetWeaver Consultant at Wipro Technologies. He is a certified SAP ABAP/4 consultant, and of the five years of experience as an SAP technical consultant he has been working on the SAP NetWeaver platform for close to two years. He has been part of end-to-end SAP Enterprise Portals and SAP XI implementation projects. 2005 SAP AG The SAP Developer Network: http://sdn.sap.com 15