Using extension fields in migration objects
In this blog I explain how to extend migration objects and provide data to the extension structure of BAPIs.
Some BAPIs support extension for customer added fields by table parameters EXTENSIONIN and EXTENSIONOUT in their interface.
In my example I will extend the migration object EQUIPMENT and provide ETM data (Equipment and Tools Management) for the append structures J_3GEQUIA and J_3GEQUZA via EXTERNSIONIN to the function module BAPI_EQUI_CREATE.
The interface of this BAPI has the extension fields:
The parameters are defined like structure BAPIPAREX:
So, you have to provide the name of a structure in field STRUCTURE and the data of all fields of the structure in the fields VALUEPART1, hence the structure must only contain character-like fields:
If you want to read more on the extension concept, you could read https://blogs.sap.com/2014/06/24/bapi-extension-for-customer-added-fields/.
This blog is based on S/4HANA 1709 FPS2 and should be valid for higher versions as well.
Update on Nov 14 2018
The creation of additional source structures was introduced in LTMOM with S/4HANA 1610 FPS2, hence, this approach does not work in older versions.
(For versions between 1610 FPS2 to 1709 FPS1 I can’t tell if it works or not.)
I performed the necessary steps for a file upload project and a staging project. The screenshots are taken from the file-based project.
The BAPI itself does not process the data in the extension fields but a BADI implementation is required. In case of BAPI BAPI_EQUI_CREATE the BADI BADI_EAM_ITOB_BAPI_CUST_FIELDS must be implemented which is not part of this blog.
Extending the Object in Migration Object Modeler
In Migration Cockpit the object EQUIPMENT only has one source structure EQUI as you can see in the view Source Structures in Migration Object Modeler (transaction LTMOM):
I prefer the technical view which displays the names of fields and structures instead of the descriptions. The view can be switched in the menu Settings à Technical Names On/Off.
The target structure EXTENSIONIN of the BAPI is a table; hence we must add a new source structure below the source structure S_EQUI. The structure EXTENSIONOUT is not required for my example.
Switch to change mode, then right-click on S_EQUI, select Append Structure to Lower Level:
Enter name and description of the additional structure and confirm. I name the structure S_EXTENSIONIN and use description “Extension Fields”:
Now add the required fields:
Field EQUNR is necessary for the migration cockpit to link the entries in this structure to the equipments in the upper level structure.
The other fields are entered as they are defined in structure EXTENSIONIN of the function module.
Now we need to link the structure to the parent structure S_EQUI by foreign key relationship:
Enter EQUNR in the first line and leave the second line initial:
Confirm and save the changes.
In Target Structures we don’t have to change anything.
In Structure Mapping we need to map our new structure S_EXTENSIONIN to the structure EXTENSIONIN by drag and drop:
Save the changes.
In Field Mapping we need to map the fields of the source structure to the corresponding fields in the target structure by drag and drop:
The field EQUNR is only needed for the link to the structure S_EQUI, so we do not map it to the target structure.
Save the changes.
Generate the object:
Testing the object
Now you can jump to Migration Cockpit (transaction LTMC) and test your extension:
After you downloaded the new xml template you see a new sheet Extension Fields; the screenshots show some sample data:
Here you fill the equipment number and the name of the extension structure and its values.
Debugging the migration object according to note 2630183 shows that the values are correctly passed to the BAPI:
Content of EXTENSIONIN structure:
The BAPI is called per single equipment, hence the table EXTENSIONIN now only contains the two lines for the first equipment in my upload file.
The processing of the data in the BAPI is not described in this blog, as mentioned above; if you need information please look at note 2146575 Customer fields in BAPIs: Technical object.
I'm glad this blog has been written now. I could have used it a few months ago. But I'm sure others will be happy to use this guide. As always I appreciate the pictures. It takes a bit more work to include them.
Thanks for the information! It's a great guide.
Now, about using staging tables. Say I added extended fields copying the objects to z versions. Then all I have to do is create the project using these objects with the staging tables option and the tables created will have the extended fields? Or do I need to go throug other steps?
Thanks for your help.
There aren't any additional steps, you only need to copy the enhanced object to the staging project and then the staging tables are created accordingly.
Really nice!! Thank you for sharing!