SAP Connector > Data integration using IDocs > Mapping and mapping tasks using IDocs

Mapping and mapping tasks using IDocs

To read and write IDocs, Data Integration integrates with SAP applications using Application Link Enabling (ALE).

ALE is an SAP proprietary technology that enables data communication between SAP systems. ALE also enables data communication between SAP and external systems.

You can configure outbound mappings to read IDocs from SAP and inbound mappings to write IDocs to SAP.

In advanced mode, the Mapping Designer updates the mapping canvas to include transformations and functions that enable advanced functionality.

To configure an outbound mapping to read IDocs from SAP, perform the following tasks:

1Configure an IDoc mapplet using the Mapplet - SAP IDoc asset from Data Integration. Verify that you selected the segments and groups you want to include in the IDoc. In addition, select the IDoc Interpreter transformation.
2Configure an outbound mapping using the generated IDoc mapplet. Add a Source transformation to read data from the SAP system, add the generated IDoc mapplet, and add a Target transformation to write the IDoc in the target object.

To configure an inbound mapping to write IDocs to SAP, perform the following tasks:

1Create an IDoc mapplet using the Mapplet - SAP IDoc asset from Data Integration. Verify that you selected the segments and groups you want to include in the IDoc. In addition, select the IDoc Prepare transformation.

Note: Do not configure multiple IDoc Prepare transformations for an IDoc mapplet in an inbound mapping on Linux. Otherwise, the mapping fails with the DTM error.

2Configure an inbound mapping using the generated IDoc mapplet. Add a Source transformation to read data from the source system, add the generated IDoc mapplet, and add a Target transformation to write the IDoc to the SAP system.

IDoc reader sources in mappings

To read IDocs from an SAP application, use an SAP IDoc Reader connection and configure the IDoc Reader source properties in the Source transformation in a mapping.

Specify the name and description of the IDoc Reader source. Configure the source and advanced properties for the source object.

The following table describes the IDoc Reader source properties that you can configure in a Source transformation:

Property	Description
Connection	Name of the source connection.
Source Type	Source type. Select Single for a single source object. When you select an SAP IDoc Reader as connection, the source type can be a single object and source object is the IDoc Reader Object. The source object has the generic structure of an IDoc message.
Object	Source object.

The following table describes the SAP IDoc Reader advanced source properties:

Property	Description
Idle Time	Indicates the number of seconds the Secure Agent waits for IDocs to arrive before it stops reading from the SAP source. For example, if you enter 30 seconds for idle time, the Secure Agent waits 30 seconds after reading from the SAP source. If no new IDocs arrive within 30 seconds, the Secure Agent stops reading from the SAP source. Default is 300.
Packet Count	Controls the number of packets the Secure Agent reads from SAP before stopping. For example, if you enter 10 for Packet Count, the Secure Agent reads the first 10 packets from the SAP source and then stops. The packet Size property in the ALE configuration determines the number of IDocs the Secure Agent receives in a packet. If you enter packet count as -1, you can read infinite number of packets. Default is -1.
Realtime Flush Latency	Determines, in seconds, how often the Secure Agent flushes data from the source.
Reader Time Limit	Sets a period of time, in seconds, during which the Secure Agent reads IDocs from the SAP source. For example, if you specify 10 as the reader time limit, the Secure Agent stops reading from the SAP source after 10 seconds. If you enter reader time limit as 0, the Security Agent continues to read IDocs from SAP for an infinite period of time. Default is 0.
Recovery Cache Folder	Specifies the location of the recovery cache folder. Note: This property is not applicable when you configure the SAP IDoc Reader Source transformation.
Number of Retries for Connection Resiliency	Determines the number of times Cloud Data Integration to attempt to connect to the SAP system. Default is 1.
Delay between Retries for Connection Resiliency	Determines the time interval in seconds between the connection retries to connect to the SAP system if it could not connect on a previous attempt. Default is 5.
Tracing Level	Sets the amount of detail that appears in the log file. You can choose terse, normal, verbose initialization or verbose data. Default is normal.

IDoc writer targets in mappings

You can use an SAP IDoc Writer connection and configure the IDoc Writer target properties in the Target transformation in a mapping.

Specify the name and description of the IDoc Writer target. Configure the target and advanced properties for the target object in a Target transformation.

The following table describes the IDoc Writer target properties that you can configure in a Target transformation:

Property	Description
Connection	Name of the target connection.
Target Type	Type of the target object.
Object	Name of the target object.

The following table describes the SAP IDoc Writer advanced target properties:

Property	Description
Packet Size	Number of IDocs that you want to send in a packet to SAP.
Number Of Retries	Not applicable.
Delay Between Retries	Not applicable.
Send IDocs Based On	The commit method of IDocs to SAP based on the value you set for the Packet Size property or commit properties at every commit point. Select one of the following options: - Packet Size. Commits IDocs to SAP based on the value you set for the Packet Size property. Data Integration collects IDoc messages until the total count reaches the packet size. It then sends messages as a packet to SAP. - Commit Call. Commits IDocs to SAP based on the commit properties at every commit point.
Generate Request ID	Not applicable.
Forward Rejected Rows	Determines whether the transformation passes rejected rows to the next transformation or drops rejected rows. By default, the agent forwards rejected rows to the next transformation.

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.

11Click Save.

Configuring an outbound mapping to read IDocs from SAP

You can configure an outbound mapping to read IDocs from SAP.

1To create a mapping, click Data Integration > New > Mappings. Select Mapping and click Create.

2Enter a name and description for the mapping, and click OK.

You can use alphanumeric characters and underscores (_) in the mapping name.

3To configure an SAP source, on the Transformation palette, click Source.

4In the Properties panel, on the General tab, enter a name and description.

5Click the Source tab and select an SAP IDoc Reader connection.

When you select an SAP IDoc Reader as connection, the source type is a single object and source object is the IDoc Reader Object.

You can also parameterize the SAP IDoc Reader connection.

6If required, configure the advanced source properties.

7To add an IDoc mapplet transformation, on the Transformation palette, click Mapplet.

aOn the General tab, enter a name and description for the mapplet.
bDraw a link to connect the previous transformation to the transformation.
cOn the Mapplet tab, click Select.

The Select Mapplet dialog box appears.

dSpecify an IDoc mapplet that you imported using the Interpreter transformation and click OK.

8To add any other transformation, on the Transformation palette, click the transformation name. Or, drag the transformation onto the mapping canvas.

aOn the General tab, enter a name and description for the transformation.
bDraw a link to connect the previous transformation to the transformation.

When you link transformations, the downstream transformation inherits the incoming fields from the previous transformation.

For a Joiner transformation, draw a master link and a detail link.

cTo preview fields, configure the field rules, or rename fields, click Incoming Fields.
dConfigure additional transformation properties, as needed.

The properties that you configure vary based on the type of transformation that you create.

eTo add another transformation, repeat these steps.

9To add a Target transformation, on the Transformation palette, click Target.

aOn the General tab, enter a name and description.
bDraw a link to connect the previous transformation to the Target transformation.
cClick the Target tab and configure target details. If required, configure the advanced target properties.

Target details and advanced target properties appear based on the connection type.

dTo preview fields, configure the field rules, or rename fields, click Incoming Fields.
eClick Field Mapping and map the fields that you want to write to the target.
fTo add another Target transformation, repeat these steps.

10Save and run the mapping. or save and create a mapping task.

For information about the source and target transformations, see Transformations.

Configuring an inbound mapping to write IDocs to SAP

You can configure an inbound mapping to write IDocs to SAP.

1To create a mapping, click Data Integration > New > Mappings. Select Mapping and click Create.

2Enter a name and description for the mapping, and click OK.

You can use alphanumeric characters and underscores (_) in the mapping name.

3To configure a source, on the Transformation palette, click Source.

4In the Properties panel, on the General tab, enter a name and description.

5Click the Source tab and configure the source details.

6To add an IDoc mapplet transformation, on the Transformation palette, click Mapplet.

aOn the General tab, enter a name and description for the mapplet.
bDraw a link to connect the previous transformation to the transformation.
cOn the Mapplet tab, click Select.

The Select Mapplet dialog box appears.

dSpecify an IDoc mapplet that you imported using the Prepare transformation and click OK.
eTo preview fields, configure the field rules, or rename fields, click Incoming Fields.

Note: You must link the DOCNUM port of the mapplet to the source transformation. The DOCNUM port represents a unique number for each IDoc and the SAP system does not accept inbound IDocs without a unique document number.

7To add any other transformation, on the Transformation palette, click the transformation name. Or, drag the transformation onto the mapping canvas.

aOn the General tab, enter a name and description for the transformation.
bDraw a link to connect the previous transformation to the transformation.

When you link transformations, the downstream transformation inherits the incoming fields from the previous transformation.

For a Joiner transformation, draw a master link and a detail link.

cTo preview fields, configure the field rules, or rename fields, click Incoming Fields.
dConfigure additional transformation properties, as needed.

The properties that you configure vary based on the type of transformation that you create.

eTo add another transformation, repeat these steps.

8To add a Target transformation, on the Transformation palette, click Target.

aOn the General tab, enter a name and description.
bDraw a link to connect the previous transformation to the Target transformation.
cClick the Target tab and configure SAP target details.
dTo preview fields, configure the field rules, or rename fields, click Incoming Fields.
eClick Field Mapping and map the fields that you want to write to the target.
fTo add another Target transformation, repeat these steps.

9Save and run the mapping or save and create a mapping task.

Outbound mapping to read MATMAS IDocs from SAP example

You can read material master (MATMAS) IDocs from SAP and write it to a relational database object.

In this example, to read the MATMAS IDocs, perform the following steps:

1Configure an IDoc mapplet with the MATMAS IDoc.
2Configure a mapping using the generated mapplet.

Step 1: Configuring an IDoc mapplet with the MATMAS IDoc

Configure an IDoc mapplet with the MATMAS IDoc from Data Integration. Use the configured mapplet to an outbound mapping.

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 IDoc Interpreter as the transformation type.

6From the Connection list, select the source connection by which you fetch the IDoc.

7From the Transformation Scope list, select Transaction.

8In the Message Type field, enter MATMAS.

9In the Basic IDoc Type field, enter MATMAS04.

10Click Fetch IDoc.

The segment details of the IDoc appears in the Select IDoc Segments section.

The image shows the segment details of the MATMAS IDoc.

11On the IDoc Document tab, in the Select IDoc Segments section, select the segments you want to include in the mapplet.

12Click Save.

Step 2: Configuring an outbound mapping with the MATMAS IDoc

Configure an outbound mapping that uses the IDoc mapplet to read the MATMAS IDoc from SAP.

1To create a mapping, click Data Integration > New > Mappings. Select Mapping and click Create.

2Enter a name and description for the mapping, and click OK.

3To configure an SAP source, on the Transformation palette, click Source.

4In the Properties panel, on the General tab, enter a name and description.

5Click the Source tab and select an SAP IDoc Reader connection.

When you select an SAP IDoc Reader as connection, the source type is a single object and source object is the IDoc Reader Object.

6If required, configure the advanced source properties.

The following image shows the SAP source details:

On the Source tab, SAP IDoc Reader connection is selected.

7To add an IDoc mapplet transformation, on the Transformation palette, click Mapplet.

8On the General tab, enter a name and description for the mapplet.

9Draw a link to connect the Source transformation to the Mapplet transformation.

10On the Mapplet tab, click Select.

The Select Mapplet dialog box appears.

11Specify an IDoc mapplet that you imported using the Interpreter transformation and click OK.

The following image shows the MATMAS mapplet details:

On the Mapplet tab, an IDoc mapplet is selected.

12To preview the incoming single IDoc Reader Object, click Incoming Fields.

The following image shows the incoming single IDoc Reader object:

A list of the incoming single IDoc Reader objects.

13Click Field Mappings to map the incoming IDoc Record field with the IDocData field in the mapplet.

14To add a Target transformation, on the Transformation palette, click Target.

15On the General tab, enter a name and description.

16Click the Target tab, and configure the required target database details.

Note: When you use IDoc Listener as a source, you can specify only those targets that honor commit. Contact Global Customer Support for the list of supported targets.

17Draw a link to connect the mapplet groups to the target database object.

18Save and run the mapping.

Inbound mapping to write IDocs to SAP example

You can create material master (MATMAS) IDocs in SAP using the MATMAS IDoc type.

In this example, to write MATMAS IDoc to SAP, perform the following steps:

1Configure an IDoc mapplet with the MATMAS IDoc.
2Configure a mapping using the generated mapplet.

Step 1: Configuring an IDoc mapplet with the MATMAS IDoc

Configure an IDoc mapplet with the MATMAS IDoc from Data Integration. Use the configured mapplet to an inbound mapping.

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 IDoc Prepare as the transformation type.

Note: Do not configure multiple IDoc Prepare transformations for an IDoc mapplet in an inbound mapping on Linux. Otherwise, the mapping fails with the DTM error.

6From the Connection list, select the source connection by which you fetch the IDoc.

7From the Transformation Scope list, select All Input.

8In the Message Type field, enter MATMAS.

9In the Basic IDoc Type field, enter MATMAS03.

10Click Fetch IDoc.

The segment details of the IDoc appears in the Select IDoc Segments section.

11On the IDoc Document tab, in the Select IDoc Segments section, select the segments you want to include in the mapplet.

12Optionally, 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.

13Click Save.

Step 2: Configuring an inbound mapping with the MATMAS IDoc

Configure an inbound mapping that uses the IDoc mapplet to write the MATMAS IDoc from SAP.

1To create a mapping, click Data Integration > New > Mappings. Select Mapping and click Create.

2Enter a name and description for the mapping, and click OK.

3To configure a flat file source, on the Transformation palette, click Source.

4In the Properties panel, on the General tab, enter a name and description.

5Click the Source tab and select an flat file connection.

6Add separate flat file sources for the control_input group and segments in the MATMAS IDoc.

7To add an IDoc Mapplet transformation, on the Transformation palette, click Mapplet.

8On the General tab, enter a name and description for the mapplet.

9On the Mapplet tab, click Select.

The Select Mapplet dialog box appears.

10Specify an IDoc mapplet that you imported using the Prepare transformation and click OK.

11Draw a link to connect the Source transformations to the Mapplet transformation. For example, connect the Control_Input source object to the Control_Input_Group for the MATMAS IDoc.

12To preview the incoming fields, click Incoming Fields.

The following image shows the incoming fields:

The configured incoming fields is displayed.

13Click Field Mappings to map the incoming fields with the mapplet input fields.

The following image shows the field mapping in the mapplet:

The Incoming Fields is mapped with the mapplet input fields to configure an inbound mapping.

14To add a Target transformation for writing to SAP, on the Transformation palette, click Target.

aOn the General tab, enter a name and description.
bClick the Target tab and configure SAP target details.

You can also parameterize the SAP target details.

15To add a flat file Target transformation for the error output, on the Transformation palette, click Target.

aOn the General tab, enter a name and description.
bClick the Target tab and configure flat file target details.

16Draw a link to connect the IDoc_Prepare_Output_Group_For_MATMAS03 to the IDocWriter object. Draw another link to connect the IDoc_Prepare_Error_Output_Group_For_MATMAS03 to the Error_Output flat file object.

The following image shows the mapping for the inbound mapping for the MATMAS IDoc:

Configured inbound mapping with the MATMAS IDoc.

17Save and run the mapping.

SAP mapplet properties

You can configure SAP mapplet properties in an outbound or inbound mapping task when you read IDocs from or write IDocs to SAP.

To configure the SAP mapplet properties, click the Runtime Options tab of the outbound or inbound mapping task. Expand the SAP Mapplet Properties section, and configure the mapplet properties.

The following table describes the SAP mapplet properties you can configure in an outbound or inbound mapping task:

Property	Outbound / Inbound	Description
Duplicate Parent Row Handling	Outbound and Inbound	Determines how Data Integration handles duplicate parent rows in a mapping task. Select one of the following options: - First Row. Data Integration passes the first duplicate row to the target. Data Integration rejects rows with the same primary key that it processes after this row. - Last Row. Data Integration passes the last duplicate row to the target. - Error. Data Integration passes the first row to the target. Rows that follow with duplicate primary keys increment the error count. The mapping task fails when the error count exceeds the error threshold. Default is First Row.
Orphan Row Handling	Outbound and Inbound	Determines how Data Integration handles orphan rows in a mapping task. Select one of the following options: - Ignore. Data Integration ignores orphan rows. - Error. The mapping task fails when the error count exceeds the error threshold. Default is Ignore.
Extended Syntax Check	Outbound and Inbound	Checks for IDocs that are not valid. If you use this property to validate IDocs, the performance of the mapping task might degrade.
Row Level Processing	Outbound	Data Integration processes each row of an outbound IDoc according to the IDoc metadata and passes it to a downstream transformation. If you enable row-level processing, Data Integration does not validate IDocs. Select this property to increase performance of the mapping task.
NULL Field Representation	Inbound	Determines how Data Integration handles fields with a null value in the IDoc prepare transformation. Select one of the following options: - Blank. Data Integration inserts all blanks for the field. - Slash (/). Data Integration inserts a single slash (/) for the field.
Cache Directory	Inbound	The directory used to cache inbound IDoc or DMI data. By default, the cache files are created in a directory specified by the variable $PMCacheDir. If you override the directory, make sure the directory exists and contains enough disk space for the cache files.
Cache Size	Inbound	Total memory in bytes allocated to Data Integration to cache data prepared for IDoc prepare transformations. Default is 10 MB.