1. Extension of IDoc types and Processing
Please pay attention to the notes when printing this document !
The IDoc Interface
Extension of IDoc types and Processing
Thomas C. Becker
SAP AG
Session Abstract: The IDoc Interface offers an enhancement concept for the interface. The concept comprises the enhancement of a given (complex) data structure together with the processing of that data structure. The enhancement is smooth for future upgrades of the SAP system. The Workshop uses an simple IDoc type derived from SAP standard, which is used in the following scenario: A customer purchases items at its vendor. The purchase order is transmitted to the vendor (simulation!). The vendor receives and processes the customer order. The process is enhanced with additional data on both, the customer and vendor, side.
Date of presentation: August, 1999
© Copyright 1999 SAP AG. All rights reserved. No part of this description of functions may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. SAP®, R/2®, R/3®, RIVA®, ABAP/4®, SAPoffice®, SAPmail®, SAPaccess®, SAP-EDI®, SAP ArchiveLink®, InterSAP®, SAP Business Workflow®, ALE®, are registered trademarks of SAP AG.

2. Exercises to Extend IDoc Processing
Agenda
Developing IDoc Interfaces
Definitions
How to Extend ?
Exercises to Extend IDoc Processing

3. Development Areas of an IDoc Process
Application
Function Module Program Report
Business Workflow
Function Module
IDoc Interface
Segment
IDoc Type
Segment Name
Segment Type
Outbound Process
Inbound Process
Data Structure
The IDoc interface comprises the data structure (given by an IDoc type) and the implementation of processing programmes for that data structure.
The interface between SAP system and EDI subsystem is given and defined by the data structure.
The processing programmes are applied between SAP application module and interface.
In outbound processing they extract data from the master and transaction records and format the data into IDoc format.
In inbound processing they create or modify an application document by the data given in IDoc format.

4. IDoc Record Types Control Record Data Record Status Record
IDoc-ID
Status information
Data Record
IDoc-ID Sequence/Hierarchy Segment
Format definition for
header data
item data
Control Record
IDoc-ID Sender-ID Receiver-ID IDoc type and logical message External structure
Each IDoc in the SAP database consists of
exact one control record,
a number of data records, which span a tree of segments, and
a set of status records, though their number grows over time.
The data to be exchanged between two systems via the IDoc interface carries in one transmission
IDocs (consisting only of control and data records), or
status information (consisting only of status records).
Status information is expected to be sent to the IDoc interface to report on outbound IDocs. There is no status information sent for inbound IDocs by SAP in general.
For individual status reporting in both directions and with all port types logical message STATUS is implemented by IDoc type SYSTAT01.
Total length of records in version 2 (Releases 3.x):
Control Record 464 bytes (plus 1 line delimiter)
Data Record 55 bytes envelope, up-to 1,000 bytes segment (plus 1 line delimiter)
Status Record 382 bytes (plus 1 line delimiter)
Total length of records in version 3 (Releases 4.x):
Control Record 524 bytes (plus 1 line delimiter)
Data Record 63 bytes envelope, up-to 1,000 bytes segment (plus 1 line delimiter)
Status Record 562 bytes (plus 1 line delimiter)

5. Basis Type = IDoc Type Extension + Definition: IDoc Type
IDoc = Intermediate Document ! An IDoc type is a hierarichal, complex data structure constructed by segments, intended to carry a complete business document. Formally basis types and extensions are distinguished as IDoc types. The instance of such a document in „IDoc format“ is an IDoc of a well-defined IDoc type.
An extension extends a basis type (SAP standard) with customer specific segments. All the customer segments are assigned in a direct or indirect way to segments of the basis type. The segments of the basis type are the „roots“ of the sub-trees constructed by the customer segments.
In the control record the IDoc type constructed by an extension is identified by the fields IDOCTYP name of the basis type, and CIMTYP name of the extension.
Examples:
IDoc type ORDERS01 as standard, i.e. without an extension:
field IDOCTYP has content ORDERS01
field CIMTYP is empty
IDoc type ORDERS01 as standard, but with an extension:
field CIMTYP has the extension‘s name as content

6. Definition: Segment Segment Type /partner/ccccc
Segment Name /partner/ccccc000
Segment Name /partner/ccccc001
Segment Name /partner/ccccc013
Segment Type E1ccccc
Segment Name E2ccccc000
Segment Name E2ccccc001
Segment Name E2ccccc013
Each segment comprises one release-independent segment type and release-dependent segment names.
The segment type as internal identifier is the development object in the ABAP workbench and repository. All its fields are of type character.
Any subsystem, e.g. EDI subsystem, will recognize the version of the segment by its segment names.
Segment types have up-to 27 character identifiers. The segment names are derived from these identifiers by appending 3 digits, starting with 000 in the first version.
SAP segments depart from that rule by using additonally also first 2 digits to distinguish segment types from segment names. Naming conventions:
SAP segment types (internal or ABAP representation) start with “E1”.
SAP segment names (external representation) start with “E2”.
Customer segments can start with “Z1” and “Z2” respectively, or use the prefix technique (concept of development prefixes).
Development partners have to use the prefix technique (concept of development prefixes).
The IDoc development tools observe the naming conventions.

7. Definition: Released & Version
By releasing segments and IDoc types the data structures of the interface are „frozen“ from the subsystems point of view. The structures are labelled with unique names to distinguish versions for segments as well as for IDoc types.
In one SAP correction level, e.g. 4.0B, only one current version can exist.
A new version of the development objects segment and IDoc type is created always, if changes are made after releasing that object.
Possible changes are strongly restricted to guarantee external compatibility of the IDoc interface.
The version of an IDoc type or segment is developed in a correction level. The latest version remains the current in all following correction levels. Not until by developing a new version it is replaced as the current one.
All versions are retained in the system, hence reductions from current versions to former versions are possible at any time. This allows the IDoc interface to serve the interface with any subsystem in a compatible mode even after upgrades.
Version of segments
It is only allowed to append fields at the end of an existing segment.
The structure of the segment type is lengthened.
A new segment name is created.
Version of IDoc types
It is only allowed to insert new segments.
A new IDoc type is created.
A new version of a segment in an IDoc type by its own, does not create a new IDoc type.
Note for outbound processing: The versions to be transmitted are maintained in the outbound partner profile:
IDoc type: by populating the IDoc type
Segment: by populating the release. This causes the IDoc interface to reduce all segments of an IDoc type to the version, i.e. lenght, of the current segment in that named release. If the release is not given always the current segment with respect to the current release is used.
Note for inbound processing: No settings are required and possible. The IDoc interface recognizes the version beeing transmitted by itself and processes the data appropriately.

8. IDoc Types - Names in ABAP Programming
Control Record, EDIDC
Status Records, EDIDS
Data Records, EDIDD
Tree of Segments
E1HDDOC M 1
E1TLSUM C
E1HDADR 5 99
E1ITSCH
E1ITDOC
In development of ABAP programs segment types only are used, e.g. with the tables declaration.
Segment types of SAP segments start with the prefix „E1“.

9. IDoc Types - Names in Subsystem
Control Record, EDI_DC40
Status Records, EDI_DS40
Data Records, by segment name
Tree of Segments
E2HDDOC* M 1
E2TLSUM* C
E2HDADR* 5 99
E2ITSCH*
E2ITDOC*
For any subsystem, e.g. an EDI subsystem, only segment names are visible.
Segment names of SAP segments start with the prefix „E2“, the „*“ is to be replaced by SPACE (first version before 4.0), or 000 (first version from 4.0 on) and 001, 002, ... For all further versions.

10. Tools to Develop an IDoc Type
Tool to define the segment with its fields
E1HDDOC
Tool to define the IDoc type with its segments
The IDoc development tools support design and definition of IDoc types and their segments by
checking the formal design rules
easy to use, common with ABAP Development Workbench
Transaction WE30. The IDoc type editor allows to define IDoc types as basis types and (customer) extensions.
Transaction WE31. The segment editor allows to define segments with their segment type and segment definitions for use in the IDoc type editor.

11. What Kind of Development, and When
The IDoc type requested is available, and matches all requirements:
Nothing to be done !
The IDoc type requested is available, but does not match in all the requirements:
Development as „extension“ !
The IDoc type requested is not available, or matches only in few requirements:
Development as „basis type“ !
Extension of an standard IDoc type, i.e. developing „extension“. This can only be done in customer project!
The customer extension, i.e. the development of an extension, is not a modification. Because of all developments are done in a separate name range, each extension can be automatically applied to a new version of the IDoc type beeing extended once.
Development of a new IDoc type, i.e. developing „basis type“. This typically is done at SAP standard development, but is as well available for customers.
The customer development is absolutly independent of the standard. Also the required processing is easily activated by the process code tables.

12. Exercises to Extend IDoc Processing
Agenda
Developing IDoc Interfaces
Definitions
How to Extend ?
Exercises to Extend IDoc Processing

13. Advantages of Extensions
The standard code of processing is still in use.
Developments and corrections of standard code are available automatically.
Extensions are much less effort than developments.

14. Fundamental Rules for Customer Extensions
Additional customer fields are assembled in separate customer segments.
Customer segments are assigned to standard segments as child-segments.
Processing of customer segments is implemented in „customer-exits“. The customer-exits are called in standard code.
Customer-exits are implemented via project management, transaction „CMOD“. Some applications, e.g. open FI, may have their own concepts for implementation of customer enhancements!

15. Areas of a Customer Extension
Application
Function Module Program Report
Business Workflow
Function Module
IDoc Interface
Segment
IDoc Type
Segment Name
Segment Type
Define data structure: In area menu „WEDI“.
Implement processing in outbound and inbound: Project management „CMOD“.
Publish documentation: In area menu „WEDI“.
Customer-exits are implemented via project management, transaction „CMOD“. Some applications, e.g. open FI, may have their own concepts for implementation of customer enhancements!

16. Steps to Extend the Data Structure
Identify the required fields, and their underlying data elements in ABAP repository.
Define the required segments with the „segment editor“.
Define the „extension“ by extending a basis type with the „IDoc type editor“.
Assign the logical message to the extension via „environment in the IDoc type editor“.
In the segment editor a field name and a data element is assigned to each field. The data element carries the documentation of the application. The field lenght in the segment is computed from that data element.
The segment editor is transaction WE31.
In the IDoc type editor a complex data structure is created by the segments. The sequence and hierarchy of the segments is defined as well as a status and iteration for all segments and segment groups. The compliance of any IDoc created (outbound: SAP application; inbound: subsystem) with its IDoc type is checked by the IDoc API. Non-compliance is reported with a syntax error (outbound: status „26“; inbound: status „60“).
The IDoc type editor is transaction WE30.

17. Steps to Extend the Processing
Create project in „project management, attributes“.
Select the „right“ customer-exit(s) in „project management, SAP enhancements“.
Implement the selected customer-exit(s) in „project management, enhancement components“.
Outbound: Read the SAP database and format data into IDoc format.
Inbound: Write data from the IDoc format to the database.
Activate project in „project management“.
Project management, transaction CMOD, radio button „Attributes“
Assign name to your project and choose „Create“.
Assign short text and select „Save“.
Select „SAP enhancement“.
Project management, transaction CMOD, radio button „SAP enhancements“
Search for customer-exit, F4 and development class as search term.
Select the required SAP enhancements and select „Copy“.
Select „Save“ and return to entry screen (F3).
Project management, transaction CMOD, radio button „Enhancement components“
Choose „Change“.
Position cursor to the component and select „Edit component“.
Double-click on the include line and follow instructions to the program editor. Remind the syntax check in the editor before saving the program and leaving the editor.
Project management, transaction CMOD
Choose „Activate project“ on the entry screen to finalize your work.

18. Outbound Call Sequence
SAP Application
Message Control IDoc Interface
IDoc Interface
Process Code Call Function ...
EDI subsystem
Customer-exit 1
Customer-exit 2
Customer-exit x

19. Inbound Call Sequence EDI subsystem IDoc Interface Customer-exit 1
Process Code Call Function ...
SAP Application
Customer-exit 1
Customer-exit 2
Customer-exit x

20. Publish Documentation of IDoc Types
Begin …
End
... typedef struct z2incodx000 { … } z2incodx000
The documentation tools are accessible from the area menu „WEDI“ of the IDoc interface, choose „Documentation“.
The documentation tools support „human“ and „machine“ readable formats:
„human“ readable formats are:
tree display inside SAP
HTML files for internet browsers (The documentation comprises 3 files: *_d.htm with the data, *_i.htm with the index and *_f.htm the frame combining data and index.)
„machine“ readable formats are:
simple language for parsers (RSEIDOC3 output)
C header declarations
meta IDoc of IDoc types SYRECD01 (record types) and SYIDOC01 (IDoc types)
Documentation of IDoc Record types: transaction WE61 Documentation of IDoc types: transaction WE60 Documentation of segments: transaction WE62 IDoc type Parser (RSEIDOC3 output): transaction WE63

21. Exercises to Extend IDoc Processing
Agenda
Developing IDoc Interfaces
Definitions
How to Extend ?
Exercises to Extend IDoc Processing

22. Exercises to Extend IDoc Processing
SAP System R/3
IDoc
Orders Light
Orders
Customer
Vendor
The exercises are taken from training BC621 „The IDoc Interface (Development)“. The following data is set-up for those exercises:
Master data: Vendor IDOC-LI-nn Purchasing organization 1000 Purchasing group 001 Plant Material in purchasing SH Order type TA Sales organization 1000 Distribution channel 10 Division 00 Customer IDOC-KU-nn Material in sales SD-EDIMAT Port SUBSYSTEM
IDoc objects: Logical message ORDLGT Basis type ORDLGT01 Extension ZEXTENnn Customer segment ZINCOnn Process code, outbound ME21-BC621-nn Process code, inbound VA01-BC621-nn Project BC621-nn SAP enhancement BC621Enn

23. Exercise 1: Start-Up
Set-up a partner profile to send purchase orders to vendor IDOC-LI-nn. The message control settings are EF / NEU / LF, the logical message is ORDLGT with process code ME21-BC621-nn.
This set-up was already done!
Create a purchase order via transaction ME21, and check with one of the monitor programs that the IDoc exists (note the IDoc‘s number).
Set-up a partner profile to receive customer orders from customer IDOC-KU-nn. The logical message is ORDLGT with process code VA01-BC621-nn.
With the test tool, transaction WE19, flip-around the IDoc created in step 2. The IDoc will serve as the customer order. Because you have changed „sites“, you have to change the control record, so it will match with your set-up in step 3.
Due to those exercises set-up, the inbound processing will fail, and the IDoc reaches status „51“: Document type NB unknown.

24. Exercise 2: Extend Inbound (Cross Reference)
You plan to overcome the error from exercise 1 by implementing a cross-reference from purchasing document type NB to sales document type TA. Hence you implement a customer-exit for the inbound processing in project management.
Create a project
Select SAP enhancements; search with development class IDOCTRAINING
Implement the exit in enhancement components
Activate your project
Test your exit by reprocessing the inbound IDoc from exercise 1 with the test tool, transaction WE19.
The IDoc now reaches status „53“: Sales document posted.
Solution for Exercise 2: 1 * * 2 * INCLUDE ZXDIXU02 3 * * 4 5 data: h_e1head like e1head. " Exercise pe_vbak621 = pi_vbak * Exercise 2 10 loop at pt_idoc_data_records 11 where segnam = 'E1HEAD'. 12 h_e1head = pt_idoc_data_records-sdata. 13 if h_e1head-auart = 'NB' pe_vbak621-auart = 'TA'. 15 endif. 16 endloop.

25. Exercise 3: Extend Outbound (Fill Field)
The IDoc type ORDLGT01 has the field NAME (ekko-ernam in purchasing) in segment E1HEAD, anyway the field is not populated by outbound processing. Hence you implement a customer-exit for the outbound processing in project management.
Create a project (With exercise 2 the project already exists!)
Select SAP enhancements; search with development class IDOCTRAINING (With exercise 2 the enhancement is already selected!)
Implement the exit in enhancement components
Activate your project
Test your exit by creating a new purchase order via transaction ME21, and check with one of the monitor programs that the IDoc exists, and the field NAME is populated.
Solution for Exercise 3: 1 * * 2 * INCLUDE ZXDIXU01 3 * * 4 5 data: k_e1head like e1head. " Exercise loop at pt_idoc_data_records 8 where segnam = 'E1HEAD'. 9 * Exercise k_e1head = pt_idoc_data_records-sdata. 11 k_e1head-name = pi_ekko-ernam. 12 pt_idoc_data_records-sdata = k_e1head. 13 modify pt_idoc_data_records. 14 endloop.

26. Exercise 4: Extend IDoc Type
You are asked to transmit „Terms of Delivery“ with your orders documents. Neither IDoc type ORDLGT01 nor one of its segments has fields for „Terms of Delivery“.
Extend the IDoc type ORDLGT01 with a 3-digit field for the code and a 28-digit field for the description of „Terms of Delivery“ (dataelements INCO1 and INCO2).
Create a customer segment Z1INCOnn
Create an extension ZEXTENnn by extending IDoc type ORDLGT01
Assign logical message ORDLGT to basis type ORDLGT01 and extension ZEXTENnn.
The processing of that extension will be implemented in the following exercises number 5 and 6.
Solution for Exercise 4:
Segment: Z1INCODX field: INCO1 dataelement: INCO1 length: 3 field: INCO2 dataelement: INCO2 length: 28
Extension: ZEXTENDX assigned to basis type ORDLGT01 segments: E1HEAD + Z1INCODX E1ITEM
IDoc type / Logical message: ORDLGT ORDLGT01 ZEXTENDX <release, e.g. 40B>

27. Exercise 5: Extend Outbound (Fill Customer Segment)
You are asked to send „Terms of Delivery“ with your orders documents. The IDoc type ORDLGT01 was already extended in exercise 4. Now you have to implement the outbound processing.
Create a project (With exercise 2 the project already exists!)
Select SAP enhancements; search with development class IDOCTRAINING (With exercise 2 the enhancement is already selected!)
Implement the exit in enhancement components
Activate your project
Because of the IDoc type is maintained in the outbound partner profile, you have to adjust the partner profile for vendor IDOC-LI-nn.
Test your exit by creating a new purchase order via transaction ME21, and check with one of the monitor programs that the IDoc exists, and the segment Z1INCOnn was populated (note the IDoc‘s number).
Solution for Exercise 5: 1 * * 2 * INCLUDE ZXDIXU01 3 * * 4 5 data: k_e1head like e1head. " Exercise 3 6 data: k_z1inco like z1incodx. " Exercise loop at pt_idoc_data_records 9 where segnam = 'E1HEAD'. 10 * Exercise k_e1head = pt_idoc_data_records-sdata. 12 k_e1head-name = pi_ekko-ernam. 13 pt_idoc_data_records-sdata = k_e1head. 14 modify pt_idoc_data_records. 15 * Exercise clear pt_idoc_data_records. 17 clear k_z1inco. 18 k_z1inco-inco1 = pi_ekko-inco k_z1inco-inco2 = pi_ekko-inco pt_idoc_data_records-segnam = 'Z1INCODX'. 21 pt_idoc_data_records-sdata = k_z1inco. 22 append pt_idoc_data_records. 23 endloop.

28. Exercise 6: Extend Inbound (Process Customer Segment)
You are asked to receive „Terms of Delivery“ with your orders documents. The IDoc type ORDLGT01 was already extended in exercise 4. Now you have to implement the inbound processing.
Create a project (With exercise 2 the project already exists!)
Select SAP enhancements; search with development class IDOCTRAINING (With exercise 2 the enhancement is already selected!)
Implement the exit in enhancement components
Activate your project
Test your exit by reprocessing the inbound IDoc from exercise 5 with the test tool, transaction WE19.
With exercise 2 the IDoc reached status „53“: Sales document posted. With the changes of this exercise also the „Terms of Delivery“ in the sales document are updated.
Solution for Exercise 6: 1 * * 2 * INCLUDE ZXDIXU02 3 * * 4 5 data: h_e1head like e1head. " Exercise 2 6 data: h_z1inco like z1incodx. " Exercise pe_vbak621 = pi_vbak * Exercise 2 11 loop at pt_idoc_data_records 12 where segnam = 'E1HEAD'. 13 h_e1head = pt_idoc_data_records-sdata. 14 if h_e1head-auart = 'NB' pe_vbak621-auart = 'TA'. 16 endif. 17 endloop * Exercise 6 20 loop at pt_idoc_data_records 21 where segnam = 'Z1INCODX'. 22 h_z1inco = pt_idoc_data_records-sdata. 23 pe_vbak621-inco1 = h_z1inco-inco pe_vbak621-inco2 = h_z1inco-inco2. 25 endloop.