BRFplus Basics – How to call a function
The usage of BRFplus and the implementation of rules is to some extent intuitive. Even if you are new to BRFplus you will be able to successfully model rules quite quickly. For sure some design decision might not be optimal on the first run but you will anyway be able to do your job. After that, some more craftmanship-like tasks have to be done namely calling your BRFplus function from the ABAP code in order to hook your function or decision service into the process flow. Writing some lines of ABAP is not a big task for a developer but, unfortunately, there are some pitfalls you can come across that in the best case just make your developer-life harder than it could be or in the worst case lead to serious performance issues. Therefore, this document shall give you a comprehensive description on how to best deal with the call of a BRFplus function.
Call of a BRFplus function
So how to call a BRFplus function? As every interface the call of a BRFplus function mainly consists of two steps: First get the parameters of your call put in the right place, second call the BRFplus function using the right piece of code i. e. the right API class that delegates to your function.
Now the first “error” that you can do is to look up how to implement that code manually. In general, there is absolutely no need to code that call from scratch. There are two options how BRFplus supports you in creating a code template you have to put at the spot where you want to call your BRFplus function like a BAdI or a User Exit. You just have to fill in the parameters at the right places and you are done. These two options will be presented in the next two sections.
Option 1 – Code Template of BRFplus Workbench
The first option to create the code you need is the BRFplus workbench itself. On the level of the function you have a button in the detail section labeled as “Create Code Template”. This is the functionality that does a lot of work for you:
What is the problem when your workbench looks like shown in the following screenshot?
The answer is that your personalization settings are in the user mode “Simple”. In order to get the functionality displayed you need to switch to the user mode “Expert” as shown in the next screenshot:
When starting the functionality a pop-up appears that displays the code for calling a BRFplus function:
Basically, all you have to do is to copy this template to the spot in the ABAP code where the function shall be called and the framework for the call is already (nearly) finished. As BRFplus does not know how to fill the single values of data objects in the signature the code template is comparable to a fill-in-the-gaps text as you have to fill the parameters of the BRFplus call with the ones you want to hand over. We will take a closer look at them in the next section.
As you can see the top line of the code template pop-up you have several options to tailor your code template:
- As a default the option “Show Comments” is active. This option triggers that the source code has some “manual-like” comments in it that guide you through the filling of the gaps in the template. After filling the code template, you can delete them as they are somewhat chatty after finishing the implementation but definitely give you guidance when completing the code template.
- The option “Enable Lean Trace” adopts the call in a manner that the lean trace recording is active when you do the function call. You find more details on tracing in the document Tracing in SAP Decision Service Management.
- The option “Return Changed Context Values” adopts the code so that the caller of the function has access to the changed context values (keep in mind that you can transfer results of a BRFplus function not only view the result data object but also via the context parameters that then act like a CHANGING parameter in ABAP).
- The option “Show result in DDIC representation” adopts the code in a manner that the result data object in the external namely the DDIC representation of the calling program. If you bound your result data object to DDIC. This is a quite helpful feature to have the result in the way you want to do the further processing with.
When you have ticked or unticked one of the options you have to press the “Apply” button in order to change the code template. There is no automatic update of the code by just ticking or unticking the option. You have to keep that in mind otherwise you might be surprised after copying your code.
Whenever you are riddling about the options and what they do the built-in Quick help of BRFplus can help as it explains the different option in some words. In order to activate it you have to activate it via the “Help” button -> Display Quick Help
After that you get the additional information on the options but just hovering over the option with your mouse pointer:
By the way, this functionality is available all over BRFplus so whenever in doubt about some options in BRFplus this little feature might help you come across that.
Option 2 – Code Template via Report
The second option how to create the code template is via an ABAP report that is part of the BRFplus. The report is called FDT_TEMPLATE_FUNCTION_PROCESS. After calling it you will see the following screen:
As one can see at once is that in contrast to the workbench you have to enter the UUID of your BRFplus function you want to create the code template for. In the BRFplus workbench this is not necessary as you create the template for an already selected function. The following options are available (unfortunately the naming of the options is not identical to the one of the BRFplus workbench although the same functionality is addressed):
- “With Comments” – this options is identical to the option “Show Comments” in the BRFplus workbench
- “Calling with Trace” – this option is identical to the option “Enable Lean Trace” in the BRFplus workbench
- “Retrieve context values” – this option is identical to the option “Return Changed Context Values” in the BRFplus workbench
- “Enforce local template” – this option is only relevant when you use SAP Decision Service Management as the code looks a bit different in that case. We will take a look at the situation with SAP Decision Service Management in the last section of the document. In a BRFplus scenario you have to keep that option ticked.
When you have entered a UUID of a function and run the report you will see the code template in the editor you can copy it from there:
As a conclusion, one can say that the functionality in the ABAP report is not as feature complete as the one of the BRFplus workbench and is is not that comfortable to use it. Nevertheless, it is good to know that an option in the ABAP world exists in order to get the code template.
Closer look – the code of the template
After creating and copying the code template let us take a look at how the BRFplus code template supports us in calling the BRFplus function. The following example does not really make sense from a business point of view, but its intention is to show different functionality that helps you in calling a BRFplus function:
- Extensive comments: The code template contains extensive comments that help you understand what happens where and getting your data into the right spots of the template:
- Depending on the type of variable you use the code to transfer the data to the BRFplus function is created. The next screenshot shows that for simple value and an amount (that is internally represented as a structure).
As you can also see it is quite obvious where there are tasks left for you i. e. the assignment of the concrete data to the BRFplus values. Nevertheless, all the other tasks (like the fetching of the reference, the appending of the parameter name-value pair to the parameter table) that can be generated are already in place
- A very nice feature is the support of the transfer of structures and table data into the BRFplus values using the method MOVE_DATA_TO_DATA_OBJECT of the class CL_FDT_FUNCTION_PROCESS. The following screenshot shows the code that is necessary to transfer a table that consists of lines of the type SFLIGHT to the parameter table that is handed over to the BRFplus function:
This is not only quite comfortable and saves a lot of lines in your ABAP code, but this is also the performance optimized way how to fill the values of your BRFplus parameters.
- In addition, the right reference concerning your result data object is created and prepared for the call of the BRFplus function.
This code snippet is also a very good example on how explanatory the comments of the code template are.
- Last but not least the call of the BRFplus function is created in the only valid way using the static method call CL_FDT_FUNCTION_PROCESS=>PROCESS:
You can also see that another best practise of ABAP code is implemented here namely the catching and handling of an exception. The comment even tells you where to find the relevant information that shall be propagated.
So shortly summarizing: Whenever you have to code a BRFplus function call use the code template as it assures that the code you use is aligned with the best practise how to do that call i. e. it ensures that all helper functionality is used in order to fill the parameters of the call correctly as well as using the right API to ensure the optimal performance of the call itself. The only thing that is left to do for you is the filling of the parameter values at the right spots.
Nogo when calling a BRFplus Function
There are some things that that are definitely a no go when implementing the call of a BRFplus function:
The first and most prominent one is the call of the BRFplus function via the outdated BRFplus API. When you used the BRFplus book of Carsten Ziegler and Thomas Albrecht to introduce you into the BRFplus you also came into touch with that API. The call of the function resembles the following code snippet:
DATA(lo_context) = lo_function->get_process_context( ).
lo_context->set_value( iv_id = lv_id
ia_value = lv_input ).
EXPORTING io_context = lo_context
IMPORTING eo_result = DATA(lo_result) ).
IMPORTING ea_value = DATA(la_result) ).
As you can see you are dealing with a concrete instance of a function in contrast to the generated call where we a central entry point is used to calling each function. The massive drawback of the call shown above is that it is extremely slow compared to the other one. So whenever you come across this outdated way of calling a BRFplus function it is heavily recommended to exchange it with the new version by using the code template.
Another issue is that you want to try to call a BRFplus expression explicitly without calling a function. This is also something the outdated call of a BRFplus function might mislead you to do but this way you switch of another functionality of the BRFplus that ensures optimal performance namely the code generation that is triggered when you call the function itself. So when you want to address just one single expression use the functional mode of the BRFplus function in order to attach one single top-level expression to it. This way your function just wraps the expression (you can see in the generated code that the overhead of the wrapping is minimal). Then use the code template to implement the function call and this way make sure that the code generation is triggered when you call the function and as a consequence the performance of the call is optimal.
SAP Decision Service Management – What is different
Up to now we have focused on calling a BRFplus function from ABAP. Are things different when you have SAP Decision Service Management (DSM) in place and want to call the function in the managed system? The answer is no and yes: No because also in this case you should use the code template to create the right piece of glue code to call your function, yes because the content of the code template differs a bit. Especially this difference often leads to some confusion.
Let us first take a look at the creation process of the code template. As in the case of the BRFplus function you can create it in the BRFplus workbench on function level:
With DSM you have the option to deploy the BRFplus function to a managed system. As a consequence you have now one more option for the code template creation. So whenever you now create a template you have to decide where/how the function shall be called. If you create a template for a local system the content of the template will be the same as the one explained above. If you create a template for a managed system the content of the template will be different, which often causes confusion as the types of the parameters as well as the classes involved are different to the call from a local system or with a BRFplus standalone system. To explain this: The different type of call is not due to some kind of remote call from the managed system to the DSM system. The code of the BRFplus function itself is deployed to the managed system so it is indeed a local call at the end. It is just a different kind of call that has to be put into the managed system in order to call the function. So as before in the scenario with BRFplus create the code template, fill-in-the-gaps for the parameters and the job is done.
The remaining functions are the same (although some slight differences arise e. g. when using the lean trace
Let us now take a look into the differences of the call. The first big difference is the typing of the parameters that you hand over to the call. In the case of BRFplus this was typed as ABAP_PARMBIND(_T). Here we have dedicated types of the DSM that contain the name value pairs of the parameters:
What remains the same is the fact that explanatory comments within the code template that support you in filling the gaps. So does the moving of simple data elements:
When moving data that is represented by a structure or a tables the call of a dedicated helper method is not necessary anymore:
Last but not least the class that processes the call is a different one namely a reference to CL_FDT_BRF_PROCESSOR. As a consequence the call looks different too:
As in the case of the BRFplus function call you can simply rely that calling the function using the code template is the best way to invoke the function.
For the sake of completeness, you can also use the report introduced before to create the code. For the DSM scenario the parameter “Enforce local template” has to be inactive.
As a bottom line: the call of a function in a managed system i. e. in a DSM scenario looks a bit different compared to the one of a plain BRFplus function call. Anyway, you should use the code template to have the right code for the function call in place and just fill your parameters at the right spots.
Calling a BRFplus function either in a BRFplus or a DSM scenario is quite easy. BRFplus/DSM offer a code template functionality that delivers the right code that you can simply copy&paste to the spot where you want to invoke that function. Fill in the gaps i. e. fill in the parameters of the call at the right places and you are finished.
Closing this document I want to cite (or at least sort of cite) very wise words of very famous person from a galaxy far away :
“Use the force code template! It binds the galaxy BRFplus function and the ABAP code together”