How to implement the Fast Change UI for 1Order documents
How to implement the Fast Change UI for 1Order documents
Performing changes for documents with many items can be a time consuming business. The first option here should always be to improve the performance as much as possible by technical optimization, by code changes and sometimes even by changing the way how the business process is set up. If you cannot make further process with this and from an end user perspective the performance is still dissatisfactory, a further option is always to push processing logic into the background. This is more likely to happen with large documents e.g. with 1000 items or more. Pushing processing logic into the background is only the second best option. One reason is of course that the system load is still generated and hardware resources are still consumed. But perhaps the bigger problem is that end users are losing the immediate feedback from the system.
The present document introduces a small framework how to integrate asynchronous actions into the normal Web UI processing. This framework will be referred to as the Fast Change UI. The intended use case is for long running steps when processing a single document. The framework will be delivered with SAP CRM EHP3 SP06.
For sales orders there is also a mass change transaction offered (Web UI component BT115MU_SLSO) which also offers an asynchronous processing mode. A guideline how to how to decide when to use the mass changes transaction versus using the Fast Change UI described here is the following: Whenever many documents should be changed at the same time use the mass change transaction. When you work with a single document but only the processing time is long use the asynchronous actions.
In the following we will describe the implementation of the Fast Change UI by the means of an example which is already delivered in standard. This means you can refer to the example in the system if you are on the required software version.
Implement a PPF action that includes the business logic and assign it to the header action profile
Choose method call as implementation method, create a new BADI implementation for BADI EXEC_METHODCALL_PPF with a new filter value and assign it to the action definition.
As usual the implementation of the action should only contain the CRM_ORDER_MAINTAIN call but not the CRM_ORDER_SAVE call. Instead it should only contain a call of method register_for_save from class CL_ACTION_EXECUTE. The implementation of the action can be found in class CL_IM_CANCEL_ITEMS.
As with all PPF actions any kind of error, warning or information can be added to the processing log of the action by calling method cl_log_ppf=>add_message.
All actions should be written on header level even if the processing of the action itself is on item level. This makes it possible to execute actions for multiple items at once. The list of items for which the action should be executed can be read from the action container with the parameter name ITEM_GUIDS.
CALL METHOD lr_action_execute->get_ref_object
io_appl_object = io_appl_object
ip_action = ip_action
ev_guid_ref = lv_header_guid.
ii_container->get_value( EXPORTING element_name = 'ITEM_GUIDS' IMPORTING data = lt_item_guid retcode = lv_rc ).
The action container allows it also bring any kind of other information needed for the execution of the action from the UI layer to the PPF layer.
For our example of the item rejection the only additional parameter is the rejection reason.
ii_container->get_value( EXPORTING element_name = 'REJECTION_REASON' IMPORTING data = lv_rejection_reason retcode = lv_rc ).
1. UI enhancements
The first step is of course to become clear from where the asynchronous action should be triggered. For header actions the natural place is the search result list for the object, e.g. the sales order search component BT115S_SLSO. The user can mark a single line and then execute the action.
There is a small problem here. If the search results into a unique result the system will automatically navigate to the overview page of the corresponding business object. Therefore it is a good idea to make the execution of the action also possible from the overview page.
For items the natural place is the item list, for sales items it is component BT115IT_SLSO.
As you can see the asynchronous actions are indicated by a little tool icon. This is not mandatory but it indicates to the user that this particular action will be executed in background.
Since the execution of the action should happen in the background it is important that the asynchronous action can only be executed in display mode.
In order to get a selection column in display mode the parameter selectionColumn of the BSP configCellerator tag needs to be set to true.
For sales orders the configuration parameter ASYNCH_ACTIONS in the UI configuration is introduced and needs to be activated only to activate the selection column.
The adding of the buttons onto the UI can be done by the usual Web UI enhancement concept. The code for the example action of cancelling items can be found in method CL_BT115IT__ITEMS_IMPL->PREPARE_TOOLBAR.
2. Implement a button event handler and trigger the action
After the user selected the action he is asked to confirm it in a popup:
Before this the system will execute a plausibility check whether the action can be executed. If not an error message will be raised in a popup:
To raise this message popup method raise_message_popup of class cl_crm_uiu_bt_tools can be used.
For the triggering of the action a button event handler needs to be implemented. To simplify the asynchronous triggering of the action the standard class CL_ACTION_TRIGGER_ASYNCH exists.
The class has two methods.
The first method CHECK_ACTION performs a check whether the actions can be executed and is meant to be called before triggering the actual execution of the action. The method performs two checks right now:
- Is the action which shall be executed part of the action profile for the current document with status active?
- Is there no SM12 lock on the current document?
If both checks are positive the check returns a positive result.
The second method TRIGGER_ACTION will actually trigger the action in the background. The method has the following import parameters
- IV_ACTION_NAME: Name of the action to be triggered
- IV_HEADER_GUID: Current header GUID
- IT_ITEM_GUID: List of item guids (optional, only for item actions)
- IT_NAME_VALUE: List of additional parameters as name value list (optional, will be listed to action container
An example event handler code for the standard example of cancelling items can be found in methods EH_ONREJECT_ASYNCH and EH_ONREJECT_ASYN_POPUP_CLOSED of class CL_BT115IT__ITEMS_IMPL.
It should be noted that IV_ACTION_NAME is not directly the name of the PPF action but there is a customizing in between. The reason is that a PPF action cannot be created with the same name in two different action profiles. This means a mapping to different PPF action names depending on the action profile needs to be possible. This mapping is done in customizing table CRMC_ASYN_ACTION.
3. Monitoring action execution
The asynchronous actions come with a monitoring view through which the action progress can be monitored. The name of the view is GSACTIONS/UserAction. The view is directly available for the Sales Professional homepage.
To make the view available at other places there a customizing entry needs to be made under the IMG path CRM->UI Framework Definition->Define Add’l View for Home Pages and Work Center Pages.
The most important fields in the monitoring view are the status description and the status traffic light.
The status can have the following values:
- Success (Green): All changes could be performed successfully
- Partially Successful (Yellow): Changes have been made but at least one error occurred
- Error (Red): An error occurred and no changes have been performed
- In Process (Yellow): The action is still being executed
By clicking on the hyperlink of the status the user has access to the log of the action. This is especially important if the action was partially successful.
After the user has checked the result of a certain action he can confirm it to make it disappear from the monitoring view.