Generating ALE Interfaces from Complex Data Types 

Use

An ALE interface can be generated from application function modules containing data of a complex data type. This enables customers as well as SAP application developers to develop new ALE scenarios with enhancements.

ALE functions such as error handling, filtering and asynchronous writing of links can still be used.

Prerequisites

Interface and Naming Convention

Function Module

An ALE interface is generated from a function module provided by the applications. This interface (function module and ALE interface) must remain stable from release to release, that is, the following rules must be followed: They are release-independent:

·        Function module interface

-          An importing parameter that transfers the data with the complex data type

-          An exporting parameter that returns the results of the processing

-          No other parameters

The importing parameter can reference a structure type for processing an individual object or reference a table type for mass processing of objects. To improve system performance, mass processing is recommended.

The parameters have to be documented in sufficient detail, including those in deeply-nested components and structures. This is especially important for the initial data transfer.

·        Processing results

The exporting parameter returns the results with a predefined structure, as follows:

a)       For individual processing - Reference to type BAPIRETS

The type BAPIRETS is a structure with the following fields:

BAPIRETS:

OBJECT_KEY	Business Document Service: Object key
OBJECT_MSG	Table type of BAPIRETC

OBJECT_KEY is the key of the processed object. OBJECT_MSG is a table type of BAPIRETC. BAPIRETC has a similar structure to BAPIRET2, whereby a new field COMPONENT with type CHAR255 has been inserted to address a component in the complex data type. This enable the applications return several messages for an object with component addresses.

b)       For mass processing – reference to type BAPIRETM

Type BAPIRETM is a table type of structure BAPIRETI.

BAPIRETI:

OBJECT_IDX	Object Index
.INCLUDE BAPIRETS	Return parameter with key for idividual object

This enables the applications to return several messages for an object determined by OBJECT_IDX.

Message type and commit work or rollback work procedures of the caller (for example, ALE layer):

Usually an object is processed by the application function module successfully or with warnings. In this case a message of type S (success) or W (warning) is returned and the callers sets a commit work.

In some cases, an object cannot be processed, e.g. if the preparation discovered an error, but the transaction could continue. Then at least one message of type E (error) will be returned. The caller sets Commit Work.

If the transaction cannot be processed further because of errors, for example, if a posting is partially made and then an error occurs and a rollback work is required. Then at least one message of type A (abort) will be returned. The caller sets a Rollback Work.

With mass processing, the Rollback Work applies to all objects. The behavior of the ALE layer in this case is described under ALE Interface.

If the exporting parameter has not been filled, this means that processing was successful. In this case the caller sets a commit work.

·        Before the interface can be delivered, it must be released

This means that compatible changes only are allowed subsequently (similar behavior as with BAPIs).

·        Enhancements to an interface that has already been released

a)       Enhancements made by the interface owner (for example, SAP)

Enhancements that are allowed include the addition of new objects:

-          New elementary fields

-          New structure types

-          New table types

-          New append structures

Modifications such as deleting existing objects or changing references are not allowed (similar behavior as with BAPIs).

b)       Enhancements made by third parties (for example, partners or customers)

-          You can only make enhancements in Append structures.

-          Modifications are not allowed.

Restrictions (see also ALE Interface section below)

A commit work is not allowed in the function module

A component with the name APPL_SNAME in the structure of the complex data type is also not allowed.

 

ALE interface

The following objects are generated from the application function module:

·         Message, IDoc structure and segments: Depiction of the complex data type

·         Outbound function module: Each IDoc always contains one application object only

·         Inbound function module: IDocs are always transferred to the application individually or in packets of objects.

·         Customizing objects required

Naming generated objects

·         Default message (maximum 30 characters) proposed from the function module name.

·         IDoc (maximum 30 characters) is derived from the message – the last two characters are extended by 01 (message <= 28 characters) or are replaced by 01 (message > 28 characters).

·         Generated module names

Outbound (maximum 30 characters): ALE_function_module_name (default)

Inbound (maximum 30 character): IDOC_INPUT_message (default)

·         Segments

The default segment name begins with E1 for SAP and Z1 for customers, or namespace /.../. A meaningful and unique segment name is assigned as follows:

-          In the application system (maximum 27 characters):

The segment name is derived from the structure name:

·         If the structure name is shorter than 24 characters, the segment name is copied directly.

·         If the structure name is longer than 23 characters, it is truncated to 23 characters by cutting off the leading, 'less significant' part. The remaining characters are used to form a number that establishes the uniqueness of the shortened name. If numbers 01 to 99 are used, assignment continues with numbers 100 to 999 until the segment name becomes unique. This also ensures that new segment names are created each time the same structure is used in the complex data type.

Example

(Namespace:/../) E1 or Z1 followed by 01..99 (shortened) structure name

 

For this reason we recommend you give the structure a meaningful name, but no longer than 23 characters.

 

-          In SAP NetWeaver (maximum 10 characters):

The segment name is mapped from the relevant structure type name.  The structure type name is the text next to the segment name, E1 or Z1, followed by the structure type name.

If the segment name is longer than 10 characters, a dialog box appears for you to enter a suitable name. If a structure is used several times in a complex data type, new segments names are requested for the same structure.

For each segment a technical field with name APPL_SNAME is inserted in the first line of the generated segment and filled by the ALE layer in runtime. This field displays the application structure from which the segment has originated. It does not have a business meaning and is therefore not relevant for applications. This also means that no component in the structure of the complex data type is allowed to be called APPL_SNAME.

Segments can be reused. This means that segments generated from the same structure can also be used in another IDoc type, provided the same structure is used in another complex data type.

Behavior of the ALE layer when you call the application module:

a)       Individual processing

If there is an A message (abort) in the exporting parameter, the ALE layer executes a rollback work.

If there is no A message (abort) in the exporting parameter, the ALE layer executes a commit work.

b)       Mass processing

If there is an A message in the exporting parameter, the ALE layer performs a rollback work for all the objects and passes the objects to the application function module again without the A and E (error) messages. The ALE layer repeats this until there are no more A messages or no more objects to process.

If there are no more A messages, a commit work is executed by the ALE layer.

IDoc status and IDoc status messages

The IDoc status is written using the exporting parameter.

a)       Individual processing

-          Status ‚51’ (Application document not updated), if there are messages of type A or E.

Status records for messages of type A and E are written.

-          Status 53 (application document posted), provided that there not a message of type A or E.

Status records are written for all messages.

If the exporting parameter has not been filled, this means that processing was successful. In this case, an IDoc status record with status 53 is written from the ALE layer.

b)       Mass processing

As with individual processing (see above), whereby all the messages are assigned to the index (OBJECT_IDX) of the appropriate object. If the index is not filled, the ALE layer assumed that die sequence is that in which objects were passed to the application.

Enhancements to an ALE interface that has already been released

a)       Enhancements made by the interface owner

The message type remains unchanged while a new IDoc type is being generated with extended segments as the successor of the existing IDoc type.

b)       Enhancements made by third parties (for example, partners or customers)

A new ALE interface is generated, that is, a new message type and IDoc type from SAP and non-SAP segments that originate from the append structures defined by third parties. F

There may be several ALE interfaces available for an application function module with a complex data type, if the complex data type is enhanced by third parties such as IBUs, partners or customers using append structures and their own ALE interface generated on this.

.

Restrictions

Fields must not be longer than 1000 bytes.

The generated IDoc type can have a maximum of 9999 segment types. At runtime ein IDoc can have up to 999.999 segment data.

Naming Convention for Applications

·         Function module name: English, meaningful. Recommended length: <= 28 characters

·         Structure name: English, meaningful. Recommended length: <= 23 characters

·         Function module name: English, meaningful. Recommended length: <= 23 characters

·         Component name: English, meaningful, NO component with name APPL_SNAME

 

For information about field names and data elements see also the BAPI Programming Guide.

 

 Additional Information

·         Generating an ALE Interface: Procedure and Implementation Model