What’s this all about?

This blog is about my experience in using the Microsoft Word Integration within the Web UI Client Framework. Primarily I use it for own documentation purposes thus I do not want to maintain lots of Word documents on my own storage any more.

In short there are three steps you have to take when using Word templates:

– create the template (Web UI application)

– create data provisioning (by implementing the later mentioned enhancement spot)

– add the function to call your Word template

The target

The business case is to print individual text-heavy letters with less dynamic Content (documents with a lot of dynamic Content (e.g. tables) should be implemented using Adobe Interactive Forms By Adobe).

Development Environment

You can start the development Environment by using the UI Component Workbench and testing the UI component  CRM_OI_TEMPLDSG.

bsp_wd_cmpwb.PNG

language to English. But you can see this as an exercise to improve your German skills (but you do not receive an certificate :-(). The following screen appears:

dtd_01.PNG

type (Objekttyp). This is the classic object type introduced a long time ago with the SAP Business Workflow environment (transaction code SWO1) type delivers the data needed for our Word template. Beside the other self explananing select-options it’s important to know that you can administrate different types of templates:

  • Microsoft Office Word (“new” XML based documents, e.g. docx)
  • Microsoft Word (old doc Format)
  • Adobe XML form

The object-type is the base for processing the Microsoft Word templates as the coding of the SAP Standard processing class CL_CRM_OI_T_TEMPLATES_IMPL references this within the method OPEN_DOCUMENT().

You receive a list of all templates available by applying the selection-criteria:

/wp-content/uploads/2014/08/result_list_497686.png

There you can find the functionality to create, edit, copy and delete templates.

Creating a new Word template

Just press the “New”-Button and the following Screen appears:

new_template_01.PNG

After filling the gaps it’s time to design the layout, this is the next step to proceed. So I thought using the button “start designer” (Designer starten) is the way to do so. But if you press this button Microsoft Word is being opened in an read-only mode – so you cannot modify the document (maybe another feature). You can find this in the following screenshot with the German word “Schreibgeschützt” (this means read-only):

word_read_only.PNG

So this is not the way we can edit our new template. Close the Microsoft Word application and you will see the “New” View again. Have a look at the radiobutton “use macros” (Makros verwenden). It seems to be a “feature” that the option to edit the template only is available when “use macros” is set to active.

Now the option for downloading (Button called “Herunterladen”) the template appears so we can edit this document locally on our client by using Microsoft Word:

new_template_02.PNG

Using merge-fields

Adding dynamic fields to the Word template is very easy. During editing your document just use the “Add Field” function and choose “merge field”. Please consider appropiate naming conventions in order to avoid confusing implementations with an outlook on the maintainance in the future.

All these merge-fields have to be accessed and filled within your BadI implementation (method GET_VALUES()).

merge_field_1.PNG

After you have finished editing the document just use the “upload functionality” (here called “Hochladen”, in the screenshot before).

Data provisioning

Now we have a closer look at the data provisioning layer. Therefore it’s essential to know the Enhancement-Spot CRM_OFFICE_INT_ENHANCEMENT. This BadI is called before the document is being opened. Thus we need an implementation of this EH-Spot.

The relevant Interface is called IF_EX_CRM_OFFICE_TEMP_BADI. It provides three methods:

Method name Description
GET_ATTRIBUTES Definition of all available field-symbols (placeholders, fields) for use within the Word templates
GET_VALUES

Provide data to the fields

  • Parameter CT_VALUES
    • the most important parameter: you have to fill this key-value-pair with the IDs of your placeholders defined within in your template and fill the values which replace the placeholders
GET_DESC_NAMES not used, yet

Go to transaction SE18 and open the mentioned enhancement spot and create a new enhancement implementation:

/wp-content/uploads/2014/08/se18_01_497870.png

You have to define the implementation’s name and assign a composite enhancement-implementation if desired. At least you have to define the class’ name. It might be a good approach to copy the pre-delivered sample class:

se18_02.PNG

After creating a new implementation class you first have to focus on the Method GET_ATTRIBUTES().field” in your template.

An implementation could look like this for the example above (merge-field names):


APPEND INITIAL LINE TO ct_attributes[] ASSIGNING <lf_attribute>.
<lf_attribute>-name = |FIRST_NAME|.
<lf_attribute>-description = space.
UNASSIGN <lf_attribute>.
APPEND INITIAL LINE TO ct_attributes[] ASSIGNING <lf_attribute>.
<lf_attribute>-Name = |LAST_NAME|.
<lf_attribute>-description = space.

The next step is to supply the attributes with values. This happens within the method GET_VALUES() which could look like this:


LOOP AT ct_values[] ASSIGNING <lf_value>. "CT_VALUES will be supplied with all the attributes added to ct_attributes[]
CASE <lf_value>-name.
WHEN 'FIRST_NAME'.
<lf_value>-value = lv_first_name. "imagine lv_first_name contains the matching attribute from BOL-model
WHEN 'LAST_NAME'.
...
ENDCASE.
ENDLOOP.

It’s recommended to implement the data provisioning logic (access to BOL-model) in a separate class in order to not overload the BadI implementation and be more flexible in the future. Maybe you’ve got many documents so it’s better to practice “separation of concern”.

Transport Management

Please keep in mind that Word templates are not connected to transport management automatically. For this you can use the report CRM_KW_TEMPLATE_TRANSPORT or use the SPRO -> CRM -> Basic functions -> Content mgmt. -> Transport template

To report this post you need to login first.

3 Comments

You must be Logged on to comment or reply to a post.

  1. Rahul Jagani

    Hi Martin,

    I read your post and have got some idea. However i would really appreciate if you can answer my below questions

    • Do we have the possibility to upload macro documents with .docm extension so that the macros work or have to use .docx extension
    • Will the badi work correctly even for the .docm extension
    • Do we have to do download template for macro word files already uploaded inorder to create the merge fields.
    • Can we create a word macro file with merge fields locally and then upload it directly. Will that work?

    Please reply back with the correct way to use the functionality if possible.

    Thanks in advance

    Rahul Jagani

    (0) 
    1. Martin Steinberg Post author

      Hi Rahul,

      first of all I do not have access to an SAP CRM system at the moment so I cannot try it out (unfortunately). I tried this out on a 731 SP10 CRM system.

      As far as I know the usage of macros within Microsoft Word documents is fraught with problems and extremly dependent on which stack our system is being hosted. So my first feeling says: do not use macros if they can be avoided.

      I only tried out docx but feel free to upload a docm template – I think it should work. Maybe you can write a statement about your experience. Therefore you must download the template as described above and upload it after updating it.

      The BadI is being called on every interaction with the MS Office integration (user interaction within the Web UI client) – it doesn’t prove the used Word document format – this only if your BadI implementation checks it (but I do not now why this should happen).

      Could you try to upload a macro loaded Word template?

      Best regards

      Martin

      (0) 
  2. Andreas Schuth

    Hey Martin 🙂

    Thanks a lot for this nice guide.

    It really helped me a lot 🙂

    One quick question regarding the “mergefields”:

    I tried to include somthing like this:

    { IF { MERGEFIELD BUAG_BUKRS } = “6” “126262” “6” }

    However it is not working. I would like to check for 3 different values of BUAG_BUKRS.

    When I use the expression “{ MERGEFIELD BUAG_BUKRS }” it will show the value e.g. “6”.

    Can you please tell if it is even possible to have a IF around a MERGEFIELD?

    Thanks in advance.

    Andreas

    (0) 

Leave a Reply