Ref: SDN Wiki.
Author: Davide Cavallari

Summary
We need to add a user-defined field to a LO-Cockpit DataSource. This field can change with no other field of the standard extract structure changing at the same time. We want this change to be registered by the DataSource's delta queue.

In the following example we will see how to add a custom field for the sales rep specified in a sales document. We will assume that the sales rep is modeled as a line-item partner function, and we will therefore enhance the DataSource 2LIS_11_VDITM (Sales Document Item Data).

Related Content
Introduction
1. Enhancing the LIS communication structure
2. Customizing the extract structure
3. Implementing the extraction logic for delta process
4. Implementing the extraction logic for the initialisation run

Introduction
The extraction process for the Logistics DataSources (those found in the LO Customising Cockpit, transaction code LBWE) is pretty complex. No wonder that, when you need to add a custom field to one of such DataSources, you have to pay especially carefull attention in order to avoid losing data from the DataSource's extraction or delta queues. On top of that, if your custom field is delta relevant as well, you may well end up with a broken delta process, where document changes are not always sent to the delta queue.

Here delta relevant means that when this field changes, this change should be felt by the V3 delta process, even though no additional field in the standard extract structure changes. It can be difficult to figure out exactly which steps are needed to ensure that the delta process works--although there is some good piece information around, such as this one, all in all I find the documentation available is pretty fragmented.

In the following I will concisely discuss an example which illustrates how to add a custom field for the sales rep specified in a sales document. We will assume that the sales rep is modeled as a line-item partner function, which in our example will have the value 'Z1'. We will therefore enhance the DataSource 2LIS_11_VDITM (Sales Document Item Data). I will not give details as to use the LO Customising Cockpit (LBWE) or implement an enhancement through the CMOD, though. If you need information about these tools, you should probably look for some specific documents on these topics as well. I do not even expalain the concept of before- and after-image records--should you need such information please refer to the related content section at the end of this document.

1. Enhancing the LIS communication structure
First of all, we need to add an extra field (YYKAM, in the example) in the LIS communication structure for sales documents' item data (MCVBAP).

We will insert an append structure (ZAMCVBAPUS, in the example) into the include structure MCVBAPUSR, and insert the new field YYKAM into this append structure:



2. Customizing the extract structure
The custom field YYKAM is now available in the LO Customizing Cockpit (transaction code LBWE), so we can add it to the extract structure MC11VA0ITM:



3. Implementing the extraction logic for delta process
In this step we will implement the code for extracting the value of the sales rep when a sales order's line item is created, modified or deleted (delta process). In the last step, instead, we will implement the extraction logic needed when performing the initialisation of a delta process.

The code for the delta extraction has to be written into the function EXIT_SAPLMCS1_002 (this function refers to the sales orders' line items) of the enhancement MCS10001 (SIS: Statistics update, sales documents). This can be done via the transaction CMOD:



Every time a line item is changed, deleted, or added, the EXIT function is called two times: one execution step processes the status of the data before the change (before-image), while the other the status after the change (after-image).

The field YY_KAM has to be filled with the value of the sales rep before or after the change, depending on whether the record is the before- or after-image. We can figure out which record is being processed through the field i_xmcvbap-supkz--its value being 1 for the before-image or 2 for the after-image record:

01.
*----------------------------------------------------------------------*
02.
* INCLUDE ZXMCVU02 *
03.
*----------------------------------------------------------------------*
04.
* importing VALUE(I_XMCVBAK) LIKE MCVBAKB STRUCTURE MCVBAKB
05.
*" VALUE(I_XMCVBUK) LIKE MCVBUKB STRUCTURE MCVBUKB
06.
*" VALUE(I_XMCVBAP) LIKE MCVBAPB STRUCTURE MCVBAPB
07.
*" VALUE(I_XMCVBUP) LIKE MCVBUPB STRUCTURE MCVBUPB
08.
*" VALUE(I_XMCVBKD) LIKE MCVBKDB STRUCTURE MCVBKDB
09.
*" VALUE(I_CONTROL) LIKE MCCONTROL STRUCTURE MCCONTROL
10.
*" EXPORTING
11.
*" VALUE(E_XMCVBAPUSR) LIKE MCVBAPUSR
12.
*" STRUCTURE MCVBAPUSR
13.
*----------------------------------------------------------------------*
14.
*
15.
* [...]
16.
*
17.
[...]
18.

19.
DATA lv_old_kz VALUE '1'.
20.
DATA lv_new_kz VALUE '2'.
21.
22.
[...]
23.
24.
CASE i_xmcvbap-supkz.
25.
26.
** before-image record
27.
WHEN lv_old_kz .
28.
29.
[...]
30.
31.
** after-image record
32.
WHEN lv_new_kz.
33.
34.
[...]
35.
36.
ENDCASE.
37.
[...]
Being the sales rep a partner function, its before- and after-image values will be read from internal tables YVBPA and XVBPA respectively. These two internal tables are defined and filled in the program SAPMV45A, and to access to their content we need to reference them through the ABAP instruction ASSIGN:

01.
FIELD-SYMBOLS:TYPE table.
02.
FIELD-SYMBOLS:TYPE table.
03.
04.
DATA lv_old_kz VALUE '1'.
05.
DATA lv_new_kz VALUE '2'.
06.
DATA tb_pa LIKE vbpavb OCCURS 0 WITH HEADER LINE.
07.
REFRESH tb_pa. CLEAR tb_pa.
08.
09.
CASE i_xmcvbap-supkz.
10.
11.
** before-image record
12.
WHEN lv_old_kz .
13.
""reference to before-image table
14.
ASSIGN ('(SAPMV45A)YVBPA[]') TO.
15.
IF sy-subrc EQ 0.
16.
tb_pa[] =.
17.
18.
[...]
19.
20.
ENDIF.
21.
22.
**after-image record
23.
WHEN lv_new_kz.
24.
""reference to after-image table
25.
ASSIGN ('(SAPMV45A)XVBPA[]') TO.
26.
IF sy-subrc EQ 0.
27.
tb_pa[] =.
28.
ENDIF.
29.
30.
ENDCASE.
31.
[...]
When users modify the sales rep in an order line item, they can enter the original value again. When this happens, the before-image and the after-image values for the field YYKAM have to be the same. In this case, however, the table YVBPA does not contain the before-image value, so we will need to fetch it from the after-image table XVBPA:
01.
** before-image record
02.
WHEN lv_old_kz .
03.
""reference to before-image table
04.
ASSIGN ('(SAPMV45A)YVBPA[]') TO.
05.
IF sy-subrc EQ 0.
06.
tb_pa[] =.
07.
08.
READ TABLE tb_pa WITH KEY parvw = 'Z1'.
09.
"Z1 is the sales rep's partner function
10.
IF sy-subrc ne 0.
11.
""when user does not change the sales rep, Y- table does not
12.
""contain the partner function Z1, so before-image state has to be
13.
""read from X- table.
14.
ASSIGN ('(SAPMV45A)XVBPA[]') TO.
15.
IF sy-subrc EQ 0.
16.
tb_pa[] =.
17.
ENDIF.
18.
ENDIF.
19.
20.
ENDIF.
Here is the complete example code:

01.
*----------------------------------------------------------------------*
02.
* INCLUDE ZXMCVU02 *
03.
*----------------------------------------------------------------------*
04.
* importing VALUE(I_XMCVBAK) LIKE MCVBAKB STRUCTURE MCVBAKB
05.
*" VALUE(I_XMCVBUK) LIKE MCVBUKB STRUCTURE MCVBUKB
06.
*" VALUE(I_XMCVBAP) LIKE MCVBAPB STRUCTURE MCVBAPB
07.
*" VALUE(I_XMCVBUP) LIKE MCVBUPB STRUCTURE MCVBUPB
08.
*" VALUE(I_XMCVBKD) LIKE MCVBKDB STRUCTURE MCVBKDB
09.
*" VALUE(I_CONTROL) LIKE MCCONTROL STRUCTURE MCCONTROL
10.
*" EXPORTING
11.
*" VALUE(E_XMCVBAPUSR) LIKE MCVBAPUSR
12.
*" STRUCTURE MCVBAPUSR
13.
*---------------------------------------------------------------------------*
14.
*
15.
* See SAP Note 216448 for information on 'before-' e 'after-image'
16.
*---------------------------------------------------------------------------*
17.
18.
FIELD-SYMBOLS:TYPE table.
19.
FIELD-SYMBOLS:TYPE table.
20.
21.
DATA lv_old_kz VALUE '1'.
22.
DATA lv_new_kz VALUE '2'.
23.
DATA tb_pa LIKE vbpavb OCCURS 0 WITH HEADER LINE.
24.
REFRESH tb_pa. CLEAR tb_pa.
25.
26.
CASE i_xmcvbap-supkz.
27.
28.
** before-image record
29.
WHEN lv_old_kz .
30.
""reference to before-image table
31.
ASSIGN ('(SAPMV45A)YVBPA[]') TO.
32.
IF sy-subrc EQ 0.
33.
tb_pa[] =.
34.
35.
READ TABLE tb_pa WITH KEY parvw = 'Z1'.
36.
IF sy-subrc ne 0.
37.
""when user does not change the sales rep, Y- table does not
38.
""contain the partner function Z1, so before-image state has to be
39.
""read from X- table.
40.
ASSIGN ('(SAPMV45A)XVBPA[]') TO.
41.
IF sy-subrc EQ 0.
42.
tb_pa[] =.
43.
ENDIF.
44.
ENDIF.
45.
46.
ENDIF.
47.
48.
** after-image record
49.
WHEN lv_new_kz.
50.
""reference to after-image table
51.
ASSIGN ('(SAPMV45A)XVBPA[]') TO.
52.
IF sy-subrc EQ 0.
53.
tb_pa[] =.
54.
ENDIF.
55.
56.
ENDCASE.
57.
58.
** we take the line-item value unless not present
59.
** in which case we take the header value
60.
READ TABLE tb_pa WITH KEY posnr = i_xmcvbap-posnr
61.
parvw = 'Z1'.
62.
IF sy-subrc NE 0.
63.
READ TABLE tb_pa WITH KEY posnr = '000000'
64.
parvw = 'Z1'.
65.
ENDIF.
66.
67.
IF sy-subrc EQ 0.
68.
MOVE tb_pa-lifnr TO e_xmcvbapusr-yykam.
69.
ENDIF.
4. Implementing the extraction logic for the initialisation run
The code in the EXIT above is only run when a sales document line is created, modified, or deleted (delta process). However, that code is not executed during the initialisation of the delta process, i.e. when all data from setup tables are loaded in BW.

In order for the extraction to take place also during the initialisation run, we need to implement the same extraction logic in the function EXIT_SAPLRSAP_001 (normally used to enhance non-LO transactional DataSources) of the enhancement RSAP0001 (Customer function calls in the service API).

Since we have already implemented the extraction logic for the delta process, we have to make sure that the code we put here is executed only when data are requested in full mode--i.e. when the field i_updmode has the value 'F' (transfer of all requested data), 'C' (initialization of the delta transfer), 'S' (simulation of initialzation of delta transfer), or 'I' (transfer of an opening balance for non-cumulative values, not relevant in our case), but not when its value is 'D' (transfer of the delta since the last request) and 'R' (repetition of the transfer of a data packet):

01.
[...]
02.
03.
CASE i_datasource.
04.
05.
[...]
06.
07.
WHEN '2LIS_11_VAITM'.
08.
DATA: s_mc11va0itm LIKE mc11va0itm.
09.
10.
LOOP AT c_t_data INTO s_mc11va0itm.
11.
wk_tabx = sy-tabix.
12.
13.
*-- The following code must be executed during initialisation only
14.
*-- (the extraction logic for delta update in EXIT_SAPLMCS6_002)
15.
*
16.
** we take the line-item value unless not present
17.
** in which case we take the header value
18.
19.
* only during initialisation
20.
IF i_updmode EQ 'F' OR " F Transfer of all requested data
21.
i_updmode EQ 'C' OR " C Initialization of the delta transfer
22.
i_updmode EQ 'S' OR " S Simulation of Initialzation of Delta Transfer
23.
i_updmode EQ 'I'. " I Transfer of an opening balance for non-cumulative values
24.
* D Transfer of the Delta Since the Last Request
25.
* R Repetition of the transfer of a data packet
26.
27.
SELECT SINGLE lifnr INTO l_lifnr
28.
FROM vbpa
29.
WHERE vbeln = s_mc11va0itm-vbeln AND
30.
posnr = s_mc11va0itm-posnr AND
31.
parvw = 'Z1'.
32.
33.
IF sy-subrc NE 0.
34.
SELECT SINGLE lifnr INTO l_lifnr
35.
FROM vbpa
36.
WHERE vbeln = s_mc11va0itm-vbeln AND
37.
posnr = '000000' AND
38.
parvw = 'Z1'.
39.
ENDIF.
40.
41.
IF sy-subrc EQ 0.
42.
MOVE l_lifnr TO s_mc11va0itm-yykam.
43.
ENDIF.
44.
ENDIF.

Requirement may come up to add new fields to LO cockpit extractor which is up & running in production environment. This means the extractor is delivering daily deltas from SAP R/3 to BW system .Since this change is to be done in R/3 Production system, there is always a risk that daily deltas of LO cockpit extractor would get disturbed. If the delta mechanism is disturbed (delta queue is broken) then there no another way than doing re-initialization for that extractor. However this re-init is not easy in terms of time & resource. Moreover no organization would be willing to provide that much downtime for live reporting based on that extractor.
As all of us know that initialization of LO Extractor is critical, resource intensive & time consuming task. Pre-requisites to perform fill setup tables are - we need to lock the users from transactional updates in R/3 system, Stop all batch jobs that update the base tables of the extractor. Then we need to schedule the setup jobs with suitable date ranges/document number ranges.
We also came across such scenario where there was a requirement to add 3 new fields to existing LO cockpit extractor 2LIS_12_VCITM. Initialization was done for this extractor 1 year back and the data volume was high.We adopted step by step approach to minimize the risk of delta queue getting broken /disturbed. Hope this step by step procedure will help all of us who have to work out similar scenarios.
Step by Step Procedure:-
1.Carry out changes in LO Cockpit extractor in SAP R/3 Dev system.As per the requirement add new fields to Extractor.These new fields might be present in standard supporting structures that you get when you execute "Maintain Data source" for extractor in LBWE. If all required fields are present in supporting structure mentioned above then just add these fields using arrow buttons provided and there is no need to write user exit code to populate these new fields.However if these fields (or some of the required fields) are not present in supporting structures then you have to go for append structure and user exit code. The coding in user exit is required to populate the newly added fields. You have to write ABAP code in User exit under CMOD & in Include ZXRSAU01.All above changes will ask you for transport request. Assign appropriate development class/Package and assign all these objects into a transport request.
2.Carry out changes in BW Dev system for objects related to this change.Carry out all necessary changes in BW Dev system for objects related to this change (Info source, transfer rules, ODS, Info cubes, Queries & workbooks). Assign appropriate development class/Package and assign all these objects into a transport request
3.Test the changes in QA system.Test the new changes in SAP R/3 and BW QA systems. Make necessary changes (if needed) and include them in follow-up transports.
4.Stop V3 batch jobs for this extractor.V3 batch jobs for this extractor are scheduled to run periodically (hourly/daily etc) Ask R/3 System Administrator to put on hold/cancel this job schedule.
5.Lock out users, batch jobs on R/3 side & stop Process chain schedule on BW.In order to avoid the changes in database tables for this extractor and hence possible risk of loss of data, ask R/3 System Administrator to lock out the users. Also batch job schedule need to be put on hold /cancel.Ask System Administrator to clear pending queues for this extractor (if any) in SMQ1/SMQ2. Also pending /error out v3 updates in SM58 should be processed.On BW production system the process chain related to delta Info package for this extractor should be stopped or put on hold.
6.Drain the delta queue to Zero for this extractor.Execute the delta Info package from BW and load the data into ODS & Info cubes. Keep executing delta Info package till you get 0 records with green light for the request on BW side. Also you should get 0 LUW entries in RSA7 for this extractor on R/3 side.
7.Import R/3 transports into R/3 Production system.In this step we import R/3 transport request related to this extractor. This will include user exit code also. Please ensure that there is no syntax error in include ZXRSAU01 and it is active. Also ensure that objects such as append structure is active after transport.
8.Replicate the data source in BW system.On BW production system, replicate the extractor (data source).
9.Import BW transport into BW Production system.In this step we import BW transport related to this change into BW Production system.
10.Run program to activate transfer rulesExecute program RS_TRANSTRU_ACTIVATE_ALL. Enter the Info source and source system name and execute. This will make sure that transfer rules for this Info source are active
11.Execute V3 job Manually in R/3 sideGo to LBWE and click on Job Control for Application area related to this extractor (for 2LIS_12_VCITM it is application 12). Execute the job immediately and it should finish with no errors.
12.Execute delta Info package from BW systemRun delta Info package from BW system. Since there is no data update, this extraction request should be green with zero records (successful delta extraction)
13.Restore the schedule on R/3 & BW systemsAsk System Administrator to resume V3 update job schedule, batch job schedule and unlock the users. On BW side, restore the process chains schedule.From next day onwards (or as per frequency), you should be able to receive the delta for this extractor with data also populated for new fields.