You can import an IDoc as a mapplet using the Mapplet - SAP IDoc asset. An IDoc contains a hierarchical structure consisting of segments. Each segment is an SAP structure defined in the SAP system.
An IDoc has header and data record components. The header component contains control information, such as creation date and status. The control information is in an SAP structure called EDIDC. The data records are in an SAP structure called EDIDD.
Segments and groups
An IDoc is a hierarchical structure that contains segments. A segment can be a parent or child. A child segment depends on another segment. A parent segment contains child segments. A parent segment can be a child of another segment.
IDoc segments are organized into groups. The following rules determine the group to which a segment belongs:
•A parent segment starts a new group. For example, in the MATMAS04 IDoc, the E1MARCM segment contains a child and therefore starts a group.
•A child segment that is not a parent belongs to the group that is started by its immediate parent. For example, in the MATMAS04 IDoc, the E1MARA1 segment does not contain a child and therefore belongs to the group of its parent E1MARAM.
•A group can also be a parent or a child.
IDocs properties
When you fetch an IDoc in Mapplet - SAP IDoc, you can view all the IDoc segments. Select a segment to view the fields in the segment.
IDocs Properties
The following table describes the IDocs properties that you can view and specify in the Mapplet - SAP IDoc asset:
Property
Description
Transformation Type
Indicates the type of transformation you want to use to generate the IDoc mapplet.
Select one of the following options:
- IDoc Prepare. Select to generate a mapplet that writes source data as an IDoc message.
- IDoc Interpreter. Select to generate a mapplet that reads IDoc messages.
Source
The source by which you fetch the IDoc.
Select one of the following options:
- Connection. Select to fetch the IDoc with an SAP Table Connector connection using the Saprfc.ini Path and Destination advanced properties.
For more information about how to create an SAP Table connection, see SAP Table Connector.
- Local file. Select to fetch the IDoc by using a file from your local drive.
Indicates how the Secure Agent applies the transformation logic to incoming data.
Select one of the following options:
- Transaction. Select Transaction to apply the transformation logic to all rows in a transaction. Select Transaction when the results of the transformation depend on all rows in the same transaction, but not on rows in other transactions. When you select Transaction, associated mappings can run in real time.
- All Input. Select All Input to apply the transformation logic to all incoming data, and to drop the incoming transaction boundaries. Select All Input when the results of the transformation depend on all rows of data in the source.
Default is All Input.
Message Type
The type of application messages that classify categories of data.
For example, ORDERS and MATMAS (Material Master).
Basic IDoc Type
The type of data structure associated with the message type.
For example, MATMAS01, MATMAS02 for MATMAS. IDocs contain the data associated with the message type.
Extended Type
Extended IDoc type name.
IDoc extension is extension of basic type and contains additional custom IDoc segments and fields that are not available in the standard basic type.
IDoc Document
Displays the IDoc segments associated with the message type and IDoc type.
Segment Name
Segment names of the IDoc type.
Description
Description of the segments.
Min Occurs
Minimum number of occurrences of the segment in an IDoc.
Max Occurs
Maximum number of occurrences of the segment in an IDoc.
Select
Selects the data segments to include in the transformation.
When you select a segment, the parent segments and all required child segments are also selected. When you clear a segment, all child segments are also cleared.
Control Record
Displays the control record segments in the IDoc, their values, and precision.
The Designer provides values for some of the segments when you create a mapplet using the IDoc prepare transformation. You can also provide values for other segments.
Segment Definition
You can view the segment field details from the segment definition section. To view the field names of the segment, select a segment name.
The following table describes the segment field details:
Field
Description
Name
Field name of a segment.
SAP Datatype
SAP data type of the field.
Precision
Precision of the field.
Scale
Scale of the field.
Description
Description of the field.
Generating IDoc metadata to local file
You can import IDoc metadata for an SAP/ALE IDoc transformation from a local file.
To import IDoc metadata from a local file, run the RSEIDoc3 program from the SAP client to generate the metadata. When you run the program, select the IDoc type and range for the IDoc metadata you want to generate. The program exports the metadata it generates into a metadata file. For example, you can export the metadata to a file with the .idc extension. You can then use the metadata file to import the metadata into the Designer for use in the SAP/ALE IDoc transformation.
To generate IDoc metadata using the RSEIDoc3 program:
1Enter transaction se38 from the SAP client.
2Execute the RSEIDoc3 program.
3Select the basic IDoc type and range.
4If you are using SAP version 5.0 or later, click Control Record.
5Optionally, select extended IDoc type and range, if available.
6Optionally, select extended grammar, if available.
7Click Parser.
8Click System > List > Save > Local File.
9On the Save List in File dialog box, select Unconverted.
10Enter the path and file name where you want to save the metadata file, and then save the file with the .idc extension.
Outbound mapplet
You can capture changes to the master data or transactional data in the SAP application database in real time.
When data in the application database changes, the SAP system creates IDocs to capture the changes and sends the IDocs to Data Integration. You can use the IDoc Reader connection to read the IDoc message in real time as they are generated by the SAP system.
If the Secure Agent is not running when the SAP system sends outbound IDocs, the Secure Agent does not receive the IDocs. However, the SAP system stores the outbound IDocs in EDI tables, which are a staging area for guaranteed message delivery. You can configure the SAP system to resend the IDocs by configuring the tRFC port used to communicate with the Secure Agent. When you configure the port, you can enable background processes in SAP that try to resend the IDocs to the Secure Agent a set number of times.
To generate the outbound mapplet to read IDoc messages from SAP system, use the IDoc Interpreter when you import the IDoc metadata. Import the outbound mapplet to Data Integration and configure an outbound mapping.
Outbound mapplet ports
An outbound IDoc mapplet contains predefined ports. You cannot edit the ports.
The following table describes the mapplet ports:
Port Name
Description
Basic IDoc Type
Basic IDoc type name.
Basic IDoc type defines the structure of an IDoc. Each basic type describes standard IDoc segments, format of data fields, and size. Basic type contains all the standard fields that are necessary for carrying out a business transaction.
Extended IDoc Type
Extended IDoc type name.
IDoc extension is extension of basic type and contains additional custom IDoc segments and fields that are not available in the standard basic type.
IDocRecord
IDoc message data.
DocumentNumber
Unique message number of the IDoc.
Target object for outbound mapplet error output
You can configure an outbound IDoc mapping to write IDocs that are not valid to a relational or flat file target. To write IDocs that are not valid to a relational or flat file target, connect the IDoc_Interpreter_Error_Output_Group port in the outbound mapplet to a relational or flat file target object. You must also configure the error log type session property in the Schedule page. Based on your requirement, you can choose to configure multiple target objects for each segment in the IDoc and for the IDoc_Interpreter_Error_Output_Group.
Inbound mapplet
You can synchronize transactional data in a legacy application with the data in the SAP application database.
Use an inbound SAP IDoc mapping to send the transactional data from the legacy application database to the SAP system. Data Integration extracts the data from the legacy application data source, prepares the data in SAP IDoc format, and sends the data to the SAP system as inbound IDocs using ALE. You can use the IDoc Writer connection to write inbound SAP IDoc messages to SAP systems.
To generate the inbound mapplet to write IDocs to SAP systems, use the Prepare transformations when you import the IDoc metadata. Import the inbound mapplet to Data Integration and configure an inbound mapping.
Key fields and control record fields
An IDoc mapplet includes a primary key (GPK) and a foreign key (GFK) in each segment. When you configure a mapping, integration template, or mapping task, map the primary key field, foreign key field, and any control record fields.
Note: You can enable control record fields when you import the IDoc metadata.
The Prepare transformation in the SAP IDoc Writer mapplet can have primary key and foreign key fields and other input fields, including control record fields.
The Prepare transformation has the following output fields:
•IDoc Data. Map this field to an IDoc target.
•Error IDoc Data. Map this field to see error messages about IDoc syntax/data conversion.
When you import IDoc metadata, you can add fields to an IDoc Prepare transformation. In Mapplet - SAP IDoc, on the Control Record tab, you can add the control record keys as key-value pairs. For example, you can add the following key-value pairs for the sender partner type and the sender partner number:
•Key: SNDPRT and Value: LS for Logical System
•Key: SNDPRN and Value ICS
In an inbound mapping, you can pass the sender partner number to SAP. You can pass a value to the CONTROL_SNDPRN port in the control input group of the Prepare transformation. If you do not connect this port to an upstream transformation, the Secure Agent uses the partner number value of SNDPRN key you specify in the Mapplet - SAP IDoc asset.
IDoc primary and foreign keys
An IDoc message is organized hierarchically with one top-level parent segment and one or more second-level child segments. Second-level child segments can also have one or more third-level child segments.
To maintain the structure of the IDoc data, the Prepare transformation in the SAP IDoc Writer mapplet uses primary and foreign keys. The top-level parent segment has a primary key. Each child segment has a primary key and a foreign key. The foreign key of each child segment references the primary key of its parent segment. For example, the foreign key of a second-level child segment references the primary key of the top-level parent segment. Similarly, the foreign key of a third-level child segment references the primary key of the second-level child segment.
The Prepare transformation groups incoming IDoc data based on the values in the primary and foreign key fields. The Control Input group of the Prepare transformation represents the parent segment. All other groups of the Prepare transformation except the ErrorIDocData group represent second-level or third-level child segments. The ErrorIDocData group is used for processing invalid IDocs.
The following table shows the groups of the Prepare transformation and the fields used for the primary and foreign keys:
Groups
Field
Description
Control Input Group
GPK_DOCNUM
Primary key of the parent segment.
Child Segment 1
GPK_<Child1_name>
Primary key of Child Segment 1.
Child Segment 1
GFK_DOCNUM_<Child1_name>
Foreign key of Child Segment 1 references the primary key of the parent segment.
Child Segment A of Child Segment 1
GPK_<Child1A_name>
Primary key of Child Segment A of Child Segment 1.
Child Segment A of Child Segment 1
GFK_<Child1_name>_<Child1A_name>
Foreign key of Child Segment A of Child Segment 1 references the primary key of Child Segment 1.
Child Segment 2
GPK_<Child2_name>
Primary key of the IDoc child segment.
Child Segment 2
GFK_DOCNUM_<Child2_name>
Foreign key of Child Segment 2 references the primary key of the parent segment.
Child Segment B of Child Segment 2
GPK_<Child2B_name>
Primary key of Child Segment B of Child Segment 2.
Child Segment B of Child Segment 2
GFK_<Child2_name>_<Child2B_name>
Foreign key of Child Segment B of Child Segment 2 references the primary key of Child Segment 2.
Each value for the GPK_<name> field needs to be unique. Each GFK_<parent_name>_<group_name> field needs to reference the primary key of its parent segment.
For example, the following table shows the relationship of primary and foreign keys in an IDoc message named ABSEN1 with four child segments:
Group
Field
Primary/Foreign Keys
CONTROL_INPUT_ABSEN1
GPK_DOCNUM
P1
E2ABSE1
GPK_E2ABSE1
C1
-
GFK_DOCNUM_E2ABSE1
P1
E2ABSE2
GPK_E2ABSE2
C2
-
GFK_DOCNUM_E2ABSE2
P1
E2ABSE2A
GPK_E2ABSE2A
C2A
-
GFK_E2ABSE2_E2ABSE2A
C2
E2ABSE3
GPK_E2ABSE3
C3
-
GFK_DOCNUM_E2ABSE3
P1
E2ABSE3B
GPK_E2ABSE3B
C3B
-
GFK_E2ABSE2_E2ABSE2A
C3
E2ABSE4
GPK_E2ABSE4
C4
-
GFK_DOCNUM_E2ABSE4
P1
The Prepare transformation uses these primary and foreign key relationships to maintain the structure of the IDoc data. Any foreign key field that does not match the primary key of its parent segment results in an orphan row. Any primary key field that is not unique results in a duplicate row.
Verify that each IDoc message has a unique primary key for the top-level parent segment, each child segment, and that each foreign key matches the primary key of its parent.
Configuring IDoc mapplets
You can configure IDoc mapplets using the Mapplet - SAP IDoc asset from Data Integration. You can use IDoc mapplets to the inbound or outbound mappings.
1In Data Integration, click New > Mapplets > Mapplet - SAP IDoc, and then click Create.
2Enter a unique name for the mapplet.
3Specify the location where you save the mapplet.
4Optionally, enter a description for the mapplet.
5Select the transformation type. You can select one of the following options:
- Select IDoc Interpreter to generate outbound mappings to read IDocs from the SAP system.
- Select IDoc Prepare to generate inbound mappings to write IDocs to the SAP system.
6Select the source by which you fetch the IDoc. You can select one of the following options:
- Select Connection to fetch the IDoc with an SAP Table Connector connection using the Saprfc.ini Path and Destination advanced properties.
Note: Ensure that you add the following entries in the sapnwrfc.ini file when you create the SAP Table connection:
DEST=PRD ASHOST=sapr3 SYSNR=01
The SAP Table connection information is available in the SAP Table Connector documentation. For more information about the SAP Table connection, see SAP Table Connector.
- Select Local File to fetch the IDoc using a file from your local drive.
7Select the scope of the transformation. You can select one of the following options:
- Select Transaction to apply the transformation logic to all rows in a transaction. Select Transaction when the results of the transformation depend on all rows in the same transaction, but not on rows in other transactions. When you select Transaction, associated mappings can run in real time. For outbound mappings, select Transaction.
- Select All Input to apply the transformation logic to all incoming data, and to drop the incoming transaction boundaries. Select All Input when the results of the transformation depend on all rows of data in the source.
8Enter the message type and the basic IDoc type, and then click Fetch IDoc.
The segment details of the IDoc appears.
9On the IDoc Document tab, in the Select IDoc Segments section, select the segments you want to include in the mapplet.
10Optionally, in an inbound mapping, to add a control record field to the mapplet, on the Control Record tab, select the checkbox for the field you want to add. This enables you to map the selected control record fields when you configure a mapping, integration template, or mapping task.