ESS – 2020 W-4….Let’s Talk Label Texts (and customization)
As a parent, you know one day the time will come where you have to have THAT talk….
“Daddy, where do the label texts come from for the SAP standard ESS W-4 webdynpro application?”
“Well son….you see….when a mommy and daddy really love each other, the SAP stork…”
No, no, no….I think we are much too old for that. You just want the truth. Straight talk. “Where in the world do the label texts come from for that W4 application?!?!?!” I had the same reaction when first digging in to figure this all out. It really was quite a mystery, but I figured it out….and hope to help save you some time. Here it is….
When looking at the standard ESS W4 webdynpro application “details” section (HRESS_C_W4 webdynpro component), you may wonder how/where the label texts are generated or can be customized. To the end user (employee), they will see:
However, if you look in the code editor looking at the webdynpro HRESS_C_W4 view V_W4 layout, we can see how the label is bound to the context for the infotype 0210 structure:
If we look at the component controller’s context, you will find node IT0210 which is mapped to data structure HCMT_BSP_PA_US_R0210. Looking at the structure in transaction SE11 if you look at each of the “text” fields, they are all defined with data element HRPAYUS_W4_TEXT. Looking at the data element, it then becomes obvious why the labels appears as “ESS W4 Text” in design mode.
However, the label does not appear the same as runtime. In fact, looking through the application, you will see nowhere that it is directly set. It’s quite the mystery!
Well, with a bit of debugging (and knowledge of other ESS WDA applications), you will find that it actually goes through the BOL (business object layer) down eventually to the good old decoupled infotype framework (DCIF). That’s where the “magic” happens within the “output conversion” method. This happens as the feeder class CL_HRESS_W4_US method IF_FPM_GUIBB_LIST~GET_DATA for the list/table shown at the top of the application is first loading as well as when rows are selected.
Now looking at the DCIF class (stay with me, we are almost there!)…..
In the “data” declarations for variables and such at the top of the method, you will see a “constant” defined for the label fields (lc_label_fields). At around line 239, the “output conversion” method will take each “label” field and call a method GET_DOCU_FIELDS.
Within that method at the very beginning at line 27, it appends a prefix to it in the code to create the object name,
CONCATENATE 'P10_W4_FED_DOCU_' iv_fieldname INTO lv_dokhl_object.
And then there is a call to standard function module DOCU_GET using that object name,
CALL FUNCTION 'DOCU_GET' EXPORTING id = 'TX' langu = sy-langu object = lv_dokhl_object typ = 'E' version_active_or_last = 'A' TABLES line = lt_docline EXCEPTIONS no_docu_on_screen = 1 no_docu_self_def = 2 no_docu_temp = 3 ret_code = 4 OTHERS = 5.
lv_dokhl_object = P10_W4_FED_DOCU_DECLARE_TXT
which will return,
These names correspond to Documentation Text objects. You can view these in transaction SE61 for example using the entries:
Click Display and you will see:
…which is similar/same as editing Standard Texts.
You can find the following texts defined:
Once the “output conversion” method runs, you will have the structure filled with values retrieved from all the related Documentation Texts:
You can see how this corresponds to the default view:
THAT is the “magic”. But what now? What if you want to create/customize your own label texts? For example, you may want to use the exact text from the official W4 form or add additional text referencing sections of the official form. To customize, you have several options. You can kind of think of it as working back from bottom to top through each layer:
- Customize the Documentation Text : Depending on your need, you could simply change the Documentation Text as you need. The downside to this approach is that you would have to keep them quite generic. For example, you could say “Filing Status”, but it would not make sense to say “Step 1c – Federal Filing Status” because that would only apply to a specific tax authority and specific form. However, if you wanted change “Additional amount, if any, you want withheld from each paycheck” to “Extra Withholding from EACH pay period”, then that would make sense in most all cases.
- Create custom “Z” DCIF UI conversion class : It is fairly typical and very easy to create your own “Z” version of the DCIF conversion class and then change configuration to use your class instead of the standard. If going this route, be aware that these conversion classes will apply to ALL uses of the DCIF for that infotype….not just in ESS. Also, as it is a custom version, any changes to the standard by SAP would need to be merged into your version. As “label” changes are aesthetic and fairly narrowed to our specific application, I tend to steer clear of this option.
- Create custom “Z” version of the feeder class : You can “trap” and change the labels during the “get data” call made in the feeder class. You could create your own “Z” version and once the “IT0210” structure is returned and filled by the conversion class, you could add your logic to make changes as needed. For many of the same reasons as the conversion class, I prefer not to make my changes here. To me, if I am going to have a custom version of the webdynpro, I prefer that at least as much of the “plumbing” underneath it stays the same, so that any SAP updates to those standard objects are still being used.
- Create custom “Z” version of the HRESS_C_W4 component and change labels directly : For just testing or “playing around”, I do not see the harm in just “hardcoding” some text into your label elements. However, as the value for these are already bound to our context which allows us the flexibility of setting them dynamically, why would you limit yourself in such a way? Just say no to hardcode!!!
- Create custom “Z” version of the HRESS_C_W4 component and change labels dynamically : If you already are making a custom “Z” version of the component itself, why not just add some code as needed to adjust the labels as you like. Again, the labels are just cosmetic so this is not really “business logic” that is better kept somewhere centrally.
I noted the reasons for/against the above options, so I will leave it to you to decide what is best for your scenario. For my own solution in our case, we had already created a custom WDA application version in order to change the view layout and some other things. In this custom version, I simply created a new method in our component controller that is called in the view’s WDDOMODIFYVIEW method. I then read the whole context node IT0210 to inspect some values (BEGDA, TAURT, etc) in order to decide what and how the text fields need to be changed, update those in the context as needed, and set the IT0210 node back. To the end user when selecting their FED filing for 2020, it appears as:
(*shout out to Jeff Wible for his excellent Java and WDA examples in the blog noted below!!!)
However, for year’s prior to 2020 for FED or for state filings, I default the labels to the original values in most cases. Because this is custom, this logic can be changed/updated as needed going forward.
As I said in my other recent W4 related blogs, I HIGHLY recommend following these other two blogs as they have been updated almost daily with information. The comments section on both are the best as an exchange of information between customers has been just as valuable as the blog content itself:
As always, hope this helps!
Very Good Blog Chris! Thanks for sharing
Very detailed and useful blog..