New XIF Interfaces 40 En

Release: 4.01

Author:

Knut Thies

CRM Component Integration

New External Interfaces

Generating New XIF Interfaces

History

Version

3.0

4.0 26.08.2002 XI Site Type; BADI Generation4.01 28.10.2002 Checklist

Original Document:

\\dwdf035\crm_ci\Development_Integration_Architecture\Projekt-XIF\Docu\New_XIF_Interfaces_40_En.doc


Table of Contents:

1 Introduction.....................................................................................................................4

2 XIF Framework Block Diagram......................................................................................4

3 Prerequisites for a new XIF Interface............................................................................5

4 Defining the XIF Metadata..............................................................................................5

4.1 Call Sequence for 1:n Interfaces..............................................................................................................7

4.2 Connecting to the eXchange Infrastructure (XI).....................................................................................7

5 Generating the XIF Framework......................................................................................7

6 Manual Intervention in Generated Modules..................................................................8

6.1 <Prefix>_<ObjectType>_MAP_TO...........................................................................................................8

6.2 <Prefix>_<ObjectType>_MAP_FROM......................................................................................................8

6.3 <Prefix>_<ObjectType>_MAP_EXTRACT................................................................................................8

6.4 <Prefix>_<ObjectType>_MAP_FILLERR.................................................................................................9

7 Generating the IDOC Interface.......................................................................................9

8 Activating Object Links................................................................................................10

8.1 Registering the Interface in the DX Workbench...................................................................................10

9 Documentation for the Interface..................................................................................11

10 Releasing the Interface............................................................................................11

10.1 Releasing the IDOC Interface:........................................................................................................12

10.2 Releasing the Function Module......................................................................................................12

10.3 Including the Function Module in the Interface Repository.........................................................12

11 Testing the Interface................................................................................................12

11.1 Inbound............................................................................................................................................ 13

11.2 Outbound......................................................................................................................................... 13

11.3 ClientToClient.................................................................................................................................. 13

/tt/file_convert/55cf92da550346f57b9a0b60/document.doc


11.4 Initial Data Processing....................................................................................................................13

11.5 BADI Implementation...................................................................................................................... 14

12 Updating IMG Activities...........................................................................................14

13 Checklist...................................................................................................................14

14 Additional Sources of Information..............................................................................15



1 Introduction

This document is aimed at CRM developers who wish to implement the new external interfaces (XIF = external interface).

The document shows which steps are necessary for realizing a new XIF interface. Based on the XIF architecture display, the necessary prerequisites, generation itself and the remaining manual steps for a complete XIF interface are executed.

2 XIF Framework Block Diagram



3 Prerequisites for a new XIF Interface

The following points are basic prerequisites for a new XIF interface

A Messaging BDoc (with complex data part) (see MW_Design_BDocModeler for more details)

A definition of a complex data type, which correctly describes the CRM object model for this object type and has been confirmed by the CRM CI Modeling Group concerning comprehensibility and correctness. Provided that the complex data part of the BDoc meets these requirements, it can also be used directly as an interface structure. This is the optimum case and should always be kept in mind for new interfaces.

A validation service that updates a Messaging BDoc. This must meet the programming guidelines/guides for the Middleware (see MW Cookbook for more details)

An extractor service that can supply a Messaging BDoc (see MW Cookbook for more details)

This means that the fundamental prerequisites for a new interface in the CRM Middleware can be met! When this is done, very little remains.

4 Defining the XIF Metadata

Table CRMXIF_BDOCIF contains all delivered interface types. The key, TR_NAME and INTERFACE_TYPE must be defined. The TR_NAME is the short name TR_GNAME from the table SMOG_TRANS of all BDocs. There is a maintenance view for table CRMXIF_BDOCIF.

The interface name should adhere to the following naming convention:

<Prefix>_<ObjectName>_SAVE

A SHORTNAME with the maximum length of 12 characters is determined from the middle part of the interface name. If the <ObjectName> is longer, first the "_" is removed, and finally the positions after the 12th character are cut off.

If no IF_DATA_TYPE is specified, the data type of the complex BDoc is transferred as the data type of the interface type.

Example

TR_NAME BUPA_MAIN Messaging BDOC type (ShortName)

INTERFACE_TYPE CRMXIF_PARTNER_SAVE Interface name

INTERFACE_FGN CRMXIF_PARTNER_GEN (Main)Function group

IF_DATA_TYPE CRMXIF_PARTNER_COMPLEX_T Interface complex data type (tabular)

MAPSEND_FN CRMXIF_PARTNER_MAPSEND Outbound function module

MAPSEND_FGN CRMXIF_PARTNER_GEN Function group

EXTRACT_FN CRMXIF_PARTNER_EXTRACT

EXTRACT_FGN CRMXIF_PARTNER_GEN Function group

MAP_FN CRMXIF_PARTNER_MAP_TO Outbound mapping

MAP_FGN CRMXIF_PARTNER_GEN Function group

SENDXML_FN CRMXIF_PARTNER_XML_SEND XML dispatch module

SENDXML_FGN CRMXIF_PARTNER_XML XML function group

SENDIDOC_FN CRMXIF_PARTNER_IDOC_SEND IDOC dispatch module

SENDIDOC_FGN CRMXIF_PARTNER_IDOC Function group



MAPFROM_FN CRMXIF_PARTNER_MAP_FROM Inbound mapping

MAPFROM_FGN CRMXIF_PARTNER_GEN Function group

ERRFILL_FN CRMXIF_PARTNER_FILLERR Assignment of error/object instance

ERRFILL_FGN CRMXIF_PARTNER_GEN Function group

ALEOUT_FN CRMXIF_PARTNER_ALE_OUT Generated IDOC outbound interface

module

CALLORDER Sequence call MAPSEND function modules

SHORTNAME PARTNER Short name for generation

SENDXI_FN SENDXI function module name

SENDXI_FGN XI function group (eXchange Infrastructure)

XI_CLASS_OUT Class for XI outbound proxy

XI_METHOD_OUT Method name for XI outbound proxy

If 12 characters are insufficient for the object name, or a less meaningful interface name results from the length restriction of 12 characters for the significant name part, then the full length (30) can also be used for the interface module name.

This is achieved most easily by specifying a corresponding SHORTNAME in the metadata before generation.

Example:

The interface is to be called CRMXIF_PRODUCT_MATERIAL_SAVE. The object name PRODUCT_MATERIAL would therefore be 4 characters too long. When determining the SHORTNAME, the generation report would remove the "_" and cut off 3 characters, that is, "PRODUCTMATER". If, however, "PROD_MAT" is specified as the SHORTNAME before generation, for example, the following names result for all other function modules or function groups.

Bdoc type PRODUCT_MAT

Interface type CRMXIF_PRODUCT_MATERIAL_SAVE

FGrp Gen CRMXIF_PROD_MAT_GEN

Data type COMXIF_PRODUCT_MATERIAL_T

MapSend FB CRMXIF_PROD_MAT_MAPSEND


Extract FB CRMXIF_PROD_MAT_EXTRACT


MapTo FB CRMXIF_PROD_MAT_MAP_TO


SendXML FB CRMXIF_PROD_MAT_XML_SEND

FGrp XML CRMXIF_PROD_MAT_XML

SendIDOC FB CRMXIF_PROD_MAT_IDOC_SEND

FGrp IDOC CRMXIF_PROD_MAT_IDOC

MapFrom FB CRMXIF_PROD_MAT_MAP_FROM


ErrFill FB CRMXIF_PROD_MAT_FILLERR


ALEOut FB CRMXIF_PROD_MAT_ALE_OUT



4.1 Call Sequence for 1:n Interfaces

If several interfaces are to be supplied from a BDoc in outbound processing, then the sequence with which the corresponding interfaces are to be called can be defined via the field CALLORDER.

Example:

Product relationships are displayed in a BDoc message via the same BDoc types. However, several messages are to be created from these at the interface; one for the products involved in the relationship itself, and one for the relationship.

On the basis of a BDoc of the type PRODUCT_MAT, the interface CRMXIF_PRODUCT_MATERIAL_SAVE must be called for the products and CRMXIF_PROD_MAT_RELATION_SAVE for the product relationship. So that the product is called before the relationship, a smaller CALLORDER than for CRMXIF_PROD_MAT_RELATION_SAVE must be assigned to the interface for CRMXIF_PRODUCT_MATERIAL_SAVE. In Customizing (CRMXIF_C1), both interfaces are registered for only one site and are called up according to CALLORDER.

4.2 Connecting to the eXchange Infrastructure (XI)

If a connection to the eXchange Infrastructure in outbound processing is desired, this can also be generated.

To do this, the interface data type must be identical to/compatible with the import parameter of the generated XI proxy module.

For this, only the following are required

XI_CLASS_OUT

Class for XI outbound proxy

XI_METHOD_OUT

Method name for XI outbound proxy

Provided that this is specified, the corresponding XI send module is also generated and the call is made in the MAP_SEND module. (For later definition of the class and method, the MAP_SEND module must be regenerated)

5 Generating the XIF Framework

The framework is generated with the report CRMXIF_MAPSEND_GENERATE. The corresponding interface is to be selected in the selection screen (several can be selected at the same time).



A notification is issued again between the updating of the metadata and the actual generation of the DDic objects. That means that only the metadata is completed and saved for the first call for an interface. Afterwards, the report must be started a second time.

If the metadata exists in its entirety or has been created, then 8(9) function modules are created per interface type in the corresponding function groups. The corresponding development class and Workbench order are requested during creation.

Existing modules are not overwritten. Exceptions are the following services when the relevant checkbox(es) is/are flagged in the selection screen.

Interface module <Prefix>_<ObjectType>_SAVE

Outbound module < Prefix >_<ObjectType>_MAPSEND

XML dispatch module < Prefix >__<ObjectType>_XML_SEND

IDOC dispatch module < Prefix >_<ObjectType>_IDOC_SEND

These services may only be changed manually in exceptional cases, and should only be overwritten when changing the corresponding template.

Essentially, no module is overwritten when there is function module documentation for it.

You can navigate to the created modules by double-clicking in the report output list.

6 Manual Intervention in Generated Modules

Manual intervention must be made after generation in the following modules:

6.1 <Prefix>_<ObjectType>_MAP_TO

Mapping from complex BDOC types to complex interface types, provided that the data types differ. Otherwise, the generated module already contains the corresponding MOVE instruction.

The module contains a BADI extension call so that intervention in Mapping can be realized in the extension case. From SAP 4.0, the BADI extension itself will also be created by generation.

The BADI definition contains 2 methods:

One for intervening in outbound mapping (CHANGE_MAPPED_DATA_OUT)

One for intervening in inbound mapping (CHANGE_MAPPED_DATA_IN).

6.2 <Prefix>_<ObjectType>_MAP_FROM

Mapping from complex interface types to complex BDOC types, provided that the data types differ. Otherwise, the generated module already contains the corresponding MOVE instruction.

Regarding BADI call, see 6.1

6.3 <Prefix>_<ObjectType>_MAP_EXTRACT

Provided that a Current_State logic is desired in outbound processing, the extractor module for selection of the data must be installed here. When installing the extractor, care must be taken that no keys are transferred for instances that have already been deleted. For performance reasons, no newly created instances are to be reselected by the extractor because these must already be contained in their entirety in the Delta message. FB CRMXIF_PARTNER_EXTRACT can serve as an example for dealing with deleted and new instances.



6.4 <Prefix>_<ObjectType>_MAP_FILLERR

The assignment of application errors to the object instance are coded here. To do this, the errors from the Middleware error table SMW_ERRTAB are displayed in the ALE error table BAPIRETM. If the assignment has already been made by SMW_ERRTAB-ERR_KEY and BAPIRETM-OBJECT_KEY, then the default coding transfers this via the generic module CRMXIF_ERROR_LINK. Otherwise, the coding must be adapted correspondingly.A link can be made to the relevant data segment via field BAPIRETC-COMPONENT in order to restrict the source of the error more precisely. Example: If an incorrect category has been entered in the business partner interface CRMXIF_PARTNER_SAVE, then link to the incorrect field with the following statement.

DATA[1]-CENTRAL_DATA-COMMON-DATA-BP_CONTROL-CATEGORY

The relevant segment would then also be highlighted in color in the ALE monitor.

7 Generating the IDOC Interface

The ALE interface module specified via the metadata is called in the generated IDOC dispatch module <Prefix>_<ObjectType>_IDOC_SEND. This must now be generated via transaction BDFG. To do this, specify the interface module <Prefix>_<ObjectType>_SAVE and a suitable business object in transaction BDFG.

The following dialog then appears. Assign the following names.

Message Type: <Prefix>_<ObjectType>_SAVE

IDOC Type: <Prefix>_<ObjectType>_SAVE01

Package: <Prefix>_<ObjectType>

The package and function groups must already exist. Use exactly the same names as those already used for generating the XIF Framework.



ALE Function Module: <Prefix>_<ObjectType>_ALE_OUT

As referred to in <Prefix>_<ObjectType>_IDOC_SEND!

Function Group: <Prefix>_<ObjectType>_IDOC

ALE Inbound Processing Module: <Prefix>_<ObjectType>_ALE_IN

Function Group: <Prefix>_<ObjectType>_IDOC

Flag: Must be set in Update Task when the application data is updated by update task. It is important here that the IDOC status and the application data are written to the database in a LUW.

Flag: Mass Processing should be set when the interface is capable of mass processing, that is, it has a tabular importing parameter.

Confirmation generates the entire IDOC interface for the interface types.

8 Activating Object Links

Direct navigation from IDOC Monitoring in the corresponding display transaction for a business object can be activated using the key of the business object from the BOR. The display is implemented using the display method for an object.

This allows

a) Navigation from ALE Monitoring to the maintenance view of the application object

b) Navigation from the maintenance view to the inbound/outbound IDOC in question

c)

To do this, the following Customizing tables must be maintained. (Here, for example, the data for the business partner)

BD95 – Maintain link object type

BUSINESSPARTNER BUT000 PARTNER

BD57 – Maintain link object type for message type

CRMXIF_PARTNER_SAVE_M BUSINESSPARTNER

BD59 – Assign link object type to an IDoc field

BUSINESSPARTNER E101CRMXIF_PARTNER_KEYS 1 PARTNER_NO 30 10

BDA4 – Assign business object to a message type

CRMXIF_PARTNER_SAVE BUS1006

8.1 Registering the Interface in the DX Workbench

Create a new registration in transaction SXDA via Goto/DX Program Library.

Specify relevant object type

Task type: LOA

Program type: IDOC



Specify interface module <Prefix>_<ObjectType>_SAVE

Optional test report, which extracts data and calls the IDOC outbound interface. With this program, the data can be created automatically in the format that can be transferred directly to the DX Workbench inbound processing. Details are available on request, or from the DX Workbench group. As an example, Report CRMXIF_PARTNER_TEST can also be copied and adapted.

9 Documentation for the Interface

Documentation for the interface is to be carried out using the function module documentation in transaction SE37. The documentation for the interface CRMXIF_PARTNER_SAVE can serve as a template, for example.

The advantages of documenting the interface using the function module are as follows:

The documentation is in the system, that is, it is always the current standard and is also directly available to the customer.

It can hence be given a version number

It is automatically transported to a translator’s inbox(Only when the transport is released! Please ensure that text modules that may be referred to have "active" status, otherwise they will not be transported to the translator’s workflow.)

It can be displayed directly from the DX Workbench Program Library

It can be extracted directly into the Interface Repository (on request)

Structuring the data for the interface is also to take place using the structure documentation (se11) in the substructures contained in the complex data type of the interface. For ease of navigation through the complex data type, it is also sensible to link structure documentation. (For example, see function module CRMXIF_PRODUCT_SAVE or structure BAPI_PRODUCT).

See also document:

\\dwdf035\crm_ci\Development_Integration_Architecture\Projekt-XIF\Docu\RICHTLINIEN_XIF_DOK_DE.pdf

10 Releasing the Interface

External interfaces have the characteristics of a BAPI, and are to be treated in exactly the same way as BAPIs concerning extensibility and downward compatibility.

10.1Releasing the IDOC Interface:

Shortly before development close or delivery, the IDOC interface must be released.

In transaction BDFG

Select Edit / IDOC Type and Segment Type/ Release.

Only one interface version can be released in a Release. If there are extensions of the interface structure before the next Release, then a new version can be released, that is, there are now 2 released versions of



the IDOC interface in the same Release. A customer for the upgraded Release does not notice it at first, because the old version continues to be used.

As long as an IDOC segment of an interface has not been released, the changed segments are always overwritten when regenerating the IDOC interface. When a segment is released, it is not overwritten, but a new version of it is created. This is a prerequisite for a customer always being able to rely on the length and offsets of a released segment version.

It is strongly advised not to release an IDOC interface at development close. In this way it is possible to deliver extensions via SP packages. One may not even know that segments have been changed incompatibly. The customer may be the first person to notice this.

Ensure that extensions or changes to a structure occur only at the end of a segment (as is the case for BAPI extensions). Extensions are also possible at different levels of a complex structure, but always only at the end. Reassigning segments from header to item, or deleting segments so that entire hierarchy levels are missing, is not allowed. Even in an interface that has not yet been released, this could possibly lead to generation problems within BDFG. In this case there is no alternative but to delete the complete interface and regenerate it.

If, for deadline reasons, it is not possible to deliver the complete functionality of an interface for the first Support Package – but you still want to give individual customers the possibility to use the interface, then release the entire interface for delivery and refer to the missing functionality in a list of limitations. This is better than first of all releasing an incomplete interface structure and delivering a “complete” version that has not been released later in the same Release. Even worse is to reset the Release, regenerate it, release it and deliver an incompatible version.

10.2Releasing the Function Module

Transaction se37

The inbound update module(*_SAVE), for example, "MYPCK_MY_OBJECT_SAVE" is released. Select "Function module / Release / Release " in the menu.

10.3Including the Function Module in the Interface Repository

A released interface must also be included in the SAP Interface Repository (http://ifr.sap.com). This takes place on request to Wolfram Hinkel, who collects the CRM interfaces and forwards them to Maic Wintel. At present, the interfaces are only extracted circa 2x yearly, so it is necessary to find out in good time when the next possible time is. Extraction may only take place when the documentation is OK semantically, grammatically and technically.

11 Testing the Interface

Typically, 4 main scenarios are tested before an interface may be released for productive operation.

Inbound

Outbound

Client To Client

Initial data transfer (Outbound)

Each case and interface requires a corresponding test catalog in the GTC. The test catalog needs to be structured for the Inbound Test so that it reflects the complex data structure and the possible methods resulting from it. Further information on the theme of XIF test catalogs/test cases are available from CRM CI QM or Michael Drexler.

All required XIF Customizing settings are described in the XIF Configuration Guide

or are documented in the system (se61) general text module CRMXIF_CUST.


http://ifr.sap.com/


11.1Inbound

The test tool for IDOC is transaction WE19 or the LSMW/DX Workbench.

For a description of the test tool XML-SOAP, see the following: \\dwdf035\crm_ci\Development_Integration_Architecture\Projekt-XIF\XIF-Test\XIF-XML-Test.doc

For an interface capable of handling mass data (tabular import parameters), the test data must also contain several lines. This is very important, because only this allows the LOOPs to be tested for correctness and also the assignment of errors and object instances. With only one object instance, errors of this kind do not occur.

Note:

You cannot create mass IDOCs using WE19. You must create each IDOC individually in Status 64. This is achieved in the partner profile (WE20) by "collecting" switches. If you have created several IDOCs in this way, you can update these IDOCs in one block with Report RBDAPP01 or BD87. For XML SOAP, you can transfer the complete block in an XML file.

11.2Outbound

The outbound transaction can be tested either via the application transaction or via a special test report (see Registering the Interface in the DX Workbench).

The created outbound documents can be checked either in we05 (IDOC) or by means of the SOAP Test Server program (\\dwdf035\crm_ci\Development_Integration_Architecture\Projekt-XIF\XIF-Test\XIF-XML-Test.doc). This test is relatively tedious and can be omitted as long as you have the possibility to carry out the ClientToClient test.

11.3ClientToClient

For the ClientToClient test, outbound processing of one CRM Client is connected with the inbound processing of a second CRM Client. See also text module "CRMXIF_CUST" (SE61) in a CRM System for further details. This describes how you must configure inbound and outbound processing.

Test data is then created and saved in the source client. Then checks are carried out in the target client that the data has arrived and matches the original.

The ClientToClient test cannot replace the pure Inbound Test because:

a) The ClientToClient test generally sends only one object, and hence errors in LOOPs or object/error assignments cannot be assessed

b) You cannot recognize whether data fields that were enhanced in outbound processing but are not necessary available in inbound processing lead to only limited possible use of the interface. (GUIDs as a prerequisite, missing Customizing, and so on.)

11.4Initial Data Processing

The initial data processing from a CRM Client to another CRM Client via a XIF_IDOC or XIF_XML site is triggered here via transaction R3AS. If you only have an outbound interface, you are restricted to checking the number of outbound documents created.

So that the site types XIF_IDOC/XIF_XML in this transaction can be selected for these BDOC types, the corresponding flow contexts in transaction R3AC1 must be maintained and delivered.

11.5BADI Implementation

Both BADI implementation for inbound mapping (MAP_FROM) and for outbound mapping (MAP_TO) are tested here for functional efficiency.

To do this, implementation of the methods



CHANGE_MAPPED_DATA_OUT Change Mapping in Outbound Processing

CHANGE_MAPPED_DATA_IN Change Mapping in Inbound Processing

are created and attempts are made to manipulate the inbound data in the implementation. To create the implementation, you require developer authorizations in the test client.

12 Updating IMG Activities

All released external interfaces are listed in the SAP IMG under

Customer Relationship Management

CRM Middleware and Related Components

Exchanging Data With External Components

XIF Adapter Setup

Overview

Dieter Krieger is responsible for the IMG activity. CRM CI (Knut Thies) collects all new interfaces and forwards the information to Dieter.

Note 0448742 is also to link to the new interface.

13 Checklist

Here is a short checklist of points that are prerequisites to release an interface.

Interface: *_SAVE

Developer responsible

DM responsible:

Released planned: CRM 4.0 SP0

Nr Check OK/Not OK Remark

Error:Reference source not found

FM Docu / DDic Docu

Error:Reference source not found

FM released

11.1 Inbound tested

11.2 Outbound tested

11.3 Client to Client tested

Error:Reference

Initial data processing tested



source not found

11.5 BADI implementation tested

12 Interface included in IMG

14 Additional Sources of Information

Note 0448742 General notes on CRM external interfaces

Configuration guide: The use of external interfaces http://service.sap.com/crm-ci (Documentation/Additional Documents/External Interfaces/ Usage of External Interfaces in CRM 3.0)

LSWM Workbench: http://service.sap.com/lsmw (Version 3.0)

DX Workbench Application Help in Transaction SXDA.

Business Connector: http://service.sap.com/connectors

XIF Templates for DXWB/LSMW http://service.sap.com/crm-ci (Documentation/Additional Documents/External Interfaces/Templates for using External Interfaces via LSMW/DX-WB )

“Cookbook”: How to exchange data via CRM Middleware MW Cookbook

Design For BDoc Modeler Enhancements CRM 3.0 MW_Design_BDocModeler


http://service.sap.com/crm-ci

http://service.sap.com/connectors

http://service.sap.com/lsmw

http://service.sap.com/crm-ci

New XIF Interfaces 40 En

Documents

Transcript of New XIF Interfaces 40 En