Red Hat Training

A Red Hat training course is available for Red Hat Fuse

123.4. Message Body for IDoc

IDoc message type

When using one of the IDoc Camel SAP endpoints, the type of the message body depends on which particular endpoint you are using.
For a sap-idoc-destination endpoint or a sap-qidoc-destination endpoint, the message body is of Document type: 
org.fusesource.camel.component.sap.model.idoc.Document
For a sap-idoclist-destination endpoint, a sap-qidoclist-destination endpoint, or a sap-idoclist-server endpoint, the message body is of DocumentList type: 
org.fusesource.camel.component.sap.model.idoc.DocumentList

The IDoc document model

For the Camel SAP component, an IDoc document is modelled using the Eclipse Modelling Framework (EMF), which provides a wrapper API around the underlying SAP IDoc API. The most important types in this model are: 
org.fusesource.camel.component.sap.model.idoc.Document
org.fusesource.camel.component.sap.model.idoc.Segment
The Document type represents an IDoc document instance. In outline, the Document interface exposes the following methods: 
// Java
package org.fusesource.camel.component.sap.model.idoc;
...
public interface Document extends EObject {
    // Access the field values from the IDoc control record
    String getArchiveKey();
    void setArchiveKey(String value);
    String getClient();
    void setClient(String value);
    ...

    // Access the IDoc document contents
    Segment getRootSegment();
}
The following kinds of method are exposed by the Document interface:
Methods for accessing the control record
Most of the methods are for accessing or modifying field values of the IDoc control record. These methods are of the form getAttributeName, setAttributeName, where AttributeName is the name of a field value (see Table 123.1, “IDoc Document Attributes”).
Method for accessing the document contents
The getRootSegment method provides access to the document contents (IDoc data records), returning the contents as a Segment object. Each Segment object can contain an arbitrary number of child segments, and the segments can be nested to an arbitrary degree.
Note, however, that the precise layout of the segment hierarchy is defined by the particular IDoc type of the document. When creating (or reading) a segment hierarchy, therefore, you must be sure to follow the exact structure as defined by the IDoc type.
The Segment type is used to access the data records of the IDoc document, where the segments are laid out in accordance with the structure defined by the document's IDoc type. In outline, the Segment interface exposes the following methods: 
// Java
package org.fusesource.camel.component.sap.model.idoc;
...
public interface Segment extends EObject, java.util.Map<String, Object> {
    // Returns the value of the '<em><b>Parent</b></em>' reference.
    Segment getParent();

    // Return a immutable list of all child segments
    <S extends Segment> EList<S> getChildren();

    // Returns a list of child segments of the specified segment type. 
    <S extends Segment> SegmentList<S> getChildren(String segmentType);

    EList<String> getTypes();

    Document getDocument();

    String getDescription();

    String getType();

    String getDefinition();

    int getHierarchyLevel();

    String getIdocType();

    String getIdocTypeExtension();

    String getSystemRelease();

    String getApplicationRelease();

    int getNumFields();

    long getMaxOccurrence();

    long getMinOccurrence();

    boolean isMandatory();

    boolean isQualified();

    int getRecordLength();

    <T> T get(Object key, Class<T> type);
}
The getChildren(String segmentType) method is particularly useful for adding new (nested) children to a segment. It returns an object of type, SegmentList, which is defined as follows: 
// Java
package org.fusesource.camel.component.sap.model.idoc;
...
public interface SegmentList<S extends Segment> extends EObject, EList<S> {
    S add();

    S add(int index);
}
Hence, to create a data record of E1SCU_CRE type, you could use Java code like the following: 
Segment rootSegment = document.getRootSegment();

Segment E1SCU_CRE_Segment = rootSegment.getChildren("E1SCU_CRE").add();

How an IDoc is related to a Document object

According to the SAP documentation, an IDoc document consists of the following main parts:
Control record
The control record (which contains the meta-data for the IDoc document) is represented by the attributes on the Document object—see Table 123.1, “IDoc Document Attributes” for details.
Data records
The data records are represented by the Segment objects, which are constructed as a nested hierarchy of segments. You can access the root segment through the Document.getRootSegment method.
Status records
In the Camel SAP component, the status records are not represented by the document model. But you do have access to the latest status value through the status attribute on the control record.

Example of creating a Document instance

For example, Example 123.1, “Creating an IDoc Document in Java” shows how to create an IDoc document with the IDoc type, FLCUSTOMER_CREATEFROMDATA01, using the IDoc model API in Java.

Example 123.1. Creating an IDoc Document in Java

// Java
import org.fusesource.camel.component.sap.model.idoc.Document;
import org.fusesource.camel.component.sap.model.idoc.Segment;
import org.fusesource.camel.component.sap.util.IDocUtil;

import org.fusesource.camel.component.sap.model.idoc.Document;
import org.fusesource.camel.component.sap.model.idoc.DocumentList;
import org.fusesource.camel.component.sap.model.idoc.IdocFactory;
import org.fusesource.camel.component.sap.model.idoc.IdocPackage;
import org.fusesource.camel.component.sap.model.idoc.Segment;
import org.fusesource.camel.component.sap.model.idoc.SegmentChildren;
...
//
// Create a new IDoc instance using the modelling classes
//


// Get the SAP Endpoint bean from the Camel context.
// In this example, it's a 'sap-idoc-destination' endpoint.
SapTransactionalIDocDestinationEndpoint endpoint =
    exchange.getContext().getEndpoint(
        "bean:SapEndpointBeanID",
        SapTransactionalIDocDestinationEndpoint.class
    );

// The endpoint automatically populates some required control record attributes
Document document = endpoint.createDocument()

// Initialize additional control record attributes
document.setMessageType("FLCUSTOMER_CREATEFROMDATA");
document.setRecipientPartnerNumber("QUICKCLNT");
document.setRecipientPartnerType("LS");
document.setSenderPartnerNumber("QUICKSTART");
document.setSenderPartnerType("LS");

Segment rootSegment = document.getRootSegment();

Segment E1SCU_CRE_Segment = rootSegment.getChildren("E1SCU_CRE").add();

Segment E1BPSCUNEW_Segment = E1SCU_CRE_Segment.getChildren("E1BPSCUNEW").add();
E1BPSCUNEW_Segment.put("CUSTNAME", "Fred Flintstone");
E1BPSCUNEW_Segment.put("FORM", "Mr.");
E1BPSCUNEW_Segment.put("STREET", "123 Rubble Lane");
E1BPSCUNEW_Segment.put("POSTCODE", "01234");
E1BPSCUNEW_Segment.put("CITY", "Bedrock");
E1BPSCUNEW_Segment.put("COUNTR", "US");
E1BPSCUNEW_Segment.put("PHONE", "800-555-1212");
E1BPSCUNEW_Segment.put("EMAIL", "fred@bedrock.com");
E1BPSCUNEW_Segment.put("CUSTTYPE", "P");
E1BPSCUNEW_Segment.put("DISCOUNT", "005");
E1BPSCUNEW_Segment.put("LANGU", "E");

Document attributes

Table 123.1, “IDoc Document Attributes” shows the control record attributes that you can set on the Document object.

Table 123.1. IDoc Document Attributes

Attribute Length SAP Field Description
archiveKey 70 ARCKEY
EDI archive key
client 3 MANDT
Client
creationDate 8 CREDAT
Date IDoc was created
creationTime 6 CRETIM
Time IDoc was created
direction 1 DIRECT
Direction
eDIMessage 14 REFMES
Reference to message
eDIMessageGroup 14 REFGRP
Reference to message group
eDIMessageType 6 STDMES
EDI message type
eDIStandardFlag 1 STD
EDI standard
eDIStandardVersion 6 STDVRS
Version of EDI standard
eDITransmissionFile 14 REFINT
Reference to interchange file
iDocCompoundType 8 DOCTYP
IDoc type
iDocNumber 16 DOCNUM
IDoc number
iDocSAPRelease 4 DOCREL
SAP Release of IDoc
iDocType 30 IDOCTP
Name of basic IDoc type
iDocTypeExtension 30 CIMTYP
Name of extension type
messageCode 3 MESCOD
Logical message code
messageFunction 3 MESFCT
Logical message function
messageType 30 MESTYP
Logical message type
outputMode 1 OUTMOD
Output mode
recipientAddress 10 RCVSAD
Receiver address (SADR)
recipientLogicalAddress 70 RCVLAD
Logical address of receiver
recipientPartnerFunction 2 RCVPFC
Partner function of receiver
recipientPartnerNumber 10 RCVPRN
Partner number of receiver
recipientPartnerType 2 RCVPRT
Partner type of receiver
recipientPort 10 RCVPOR
Receiver port (SAP System, EDI subsystem)
senderAddress SNDSAD
Sender address (SADR)
senderLogicalAddress 70 SNDLAD
Logical address of sender
senderPartnerFunction 2 SNDPFC
Partner function of sender
senderPartnerNumber 10 SNDPRN
Partner number of sender
senderPartnerType 2 SNDPRT
Partner type of sender
senderPort 10 SNDPOR
Sender port (SAP System, EDI subsystem)
serialization 20 SERIAL
EDI/ALE: Serialization field
status 2 STATUS
Status of IDoc
testFlag 1 TEST
Test flag

Setting document attributes in Java

When setting the control record attributes in Java (from Table 123.1, “IDoc Document Attributes”), the usual convention for Java bean properties is followed. That is, a name attribute can be accessed through the getName and setName methods, for getting and setting the attribute value. For example, the iDocType, iDocTypeExtension, and messageType attributes can be set as follows on a Document object: 
// Java
document.setIDocType("FLCUSTOMER_CREATEFROMDATA01");
document.setIDocTypeExtension("");
document.setMessageType("FLCUSTOMER_CREATEFROMDATA");

Setting document attributes in XML

When setting the control record attributes in XML, the attributes must be set on the idoc:Document element. For example, the iDocType, iDocTypeExtension, and messageType attributes can be set as follows: 
<?xml version="1.0" encoding="ASCII"?>
<idoc:Document ...
               iDocType="FLCUSTOMER_CREATEFROMDATA01"
               iDocTypeExtension=""
               messageType="FLCUSTOMER_CREATEFROMDATA" ... >
    ...
</idoc:Document>