Navigating the BOPF: Part 3 – Working with the BOPF API

In my previous blog post, we explored the anatomy of business objects within the BOPF. There, we were able to observe the various entities that make up a BO: nodes/attributes, actions, associations, determinations, validations, and queries. Now that you have a feel for what these entities are, we’re ready to begin taking a look at the API that is used to manipulate these entities. To guide us through this demonstration, we’ll explore the construction of a simple ABAP report program used to perform CRUD operations on a sample BOPF BO shipped by default by SAP: /BOBF/DEMO_CUSTOMER. You can download the complete example program source code here.

Note: The code bundle described above has been enhanced as of 9/18/2013. The code was reworked to factor out a BOPF utilities class of sorts and also demonstrate how to traverse over to dependent objects (DOs).

BOPF API Overview

Before we begin coding with the BOPF API, let’s first take a look at its basic structure. The UML class diagram below highlights some of the main classes that make up the BOPF API. At the end of the day, there are three main objects that we’ll be working with to perform most of the operations within the BOPF:

/BOBF/IF_TRA_TRANSACTION_MGR

This object reference provides a transaction manager which can be used to manage transactional changes. Such transactions could contain a single step (e.g. update node X) or be strung out across multiple steps (add a node, call an action, and so on).

/BOBF/IF_TRA_SERVICE_MANAGER

The service manager object reference provides us with the methods we need to lookup BO nodes, update BO nodes, trigger validations, perform actions, and so on.

/BOBF/IF_FRW_CONFIGURATION

This object reference provides us with metadata for a particular BO. We’ll explore the utility of having access to this metadata coming up shortly.

In the upcoming sections, I’ll show you how these various API classes collaborate in typical BOPF use cases. Along the way, we’ll encounter other useful classes that can be used to perform specific tasks. You can find a complete class listing within package /BOBF/MAIN.

Note: As you’ll soon see, the BOPF API is extremely generic in nature. While this provides tremendous flexibility, it also adds a certain amount of tedium to common tasks. Thus, in many applications, you may find that SAP has elected to wrap the API up in another API that is more convenient to work with. For example, in the SAP EHSM solution, SAP defines an “Easy Node Access” API which simplfies the way that developers traverse BO nodes, perform updates, and so on.

Case Study: Building a Simple Report Program to Manipulate Customer Objects

To demonstrate the BOPF API, we’ll build a custom report program which performs basic CRUD operations on a sample BO provided by SAP: /BOBF/DEMO_CUSTOMER. The figure below shows the makeup of this BO in Transaction /BOBF/CONF_UI.

Our sample program provides a basic UI as shown below. Here, users have the option of creating, changing, and displaying a particular customer using its ID number. Sort of a simplified Transaction XK01-XK03 if you will.

Getting Started

To drive the application functionality, we’ll create a local test driver class called LCL_DEMO. As you can see in the code excerpt below, this test driver class loads the core BOPF API objects at setup whenever the CONSTRUCTOR method is invoked. Here, the factory classes illustrated in the UML class diagram shown in the previous section are used to load the various object references.

For the most part, this should seem fairly straightforward. However, you might be wondering where I came up with the IV_BO_KEY parameter in the GET_SERVICE_MANAGER() and GET_CONFIGURATION() factory method calls. This value is provided to us via the BO’s constants interface (/BOBF/IF_DEMO_CUSTOMER_C in this case) which can be found within the BO configuration in Transaction /BOBF/CONF_UI (see below). This auto-generated constants interface provides us with a convenient mechanism for addressing a BO’s key, its defined nodes, associations, queries, and so on. We’ll end up using this interface quite a bit during the course of our development.

Creating New Customers

Once we have the basic framework in place, we are ready to commence with the development of the various CRUD operations that our application will support. To get things started, we’ll take a look at the creation of a new customer instance. For the most part, this involves little more than a call to the MODIFY() method of the /BOBF/IF_TRA_SERVICE_MANAGER object reference. Of course, as you can see in the code excerpt below, there is a fair amount of setup that we must do before we can call this method.

"Build the ROOT_LONG_TEXT node: "If you look at the node type for this node, you'll notice that "it's a "Delegated Node". In other words, it is defined in terms "of the /BOBF/DEMO_TEXT_COLLECTION business object. The following "code accounts for this indirection. CREATE DATA lr_s_txt_hdr. lr_s_txt_hdr->key = /bobf/cl_frw_factory=>get_new_key( ).

As you can see in the code excerpt above, the majority of the code is devoted to building a table which is passed in the IT_MODIFICATION parameter of the MODIFY() method. Here, a separate record is created for each node row that is being modified (or inserted in this case). This record contains information such as the node object key (NODE), the edit mode (CHANGE_MODE), the row key (KEY) which is an auto-generated GUID, association/parent key information, and of course, the actual data (DATA). If you’ve ever worked with ALE IDocs, then this will probably feel vaguely familiar.

Looking more closely at the population of the node row data, you can see that we’re working with data references which are created dynamically using the CREATE DATA statement. This indirection is necessary since the BOPF API is generic in nature. You can find the structure definitions for each node by double-clicking on the node in Transaction /BOBF/CONF_UI and looking at the Combined Structure field (see below).

Once the modification table is filled out, we can call the MODIFY() method to insert the record(s). Assuming all is successful, we can then commit the transaction by calling the SAVE() method on the /BOBF/IF_TRA_TRANSACTION_MANAGER instance. Should any errors occur, we can display the error messages using methods of the /BOBF/IF_FRW_MESSAGE object reference which is returned from both methods. This is evidenced by the simple utility method DISPLAY_MESSAGES() shown below. That’s pretty much all there is to it.

Performing Customer Queries

If you look closely at the customer creation code illustrated in the previous section, you can see that each node row is keyed by an auto-generated GUID of type /BOBF/CONF_KEY (see below). Since most users don’t happen to have 32-character hex strings memorized, we typically have to resort to queries if we want to find particular BO instances. For example, in our customer demo program, we want to provide a way for users to lookup customers using their customer ID value. Of course, we could have just as easily defined an alternative query selection to pull the customer records.

As we learned in the previous blog post, most BOs come with one or more queries which allow us to search for BOs according to various node criteria. In the case of the /BOBF/DEMO_CUSTOMER business object, we want to use the SELECT_BY_ATTRIBUTES query attached to the ROOT node (see below). This allows us to lookup customers by their ID value.

The code excerpt below shows how we defined our query in a method called GET_CUSTOMER_FOR_ID(). As you can see, the query is executed by calling the aptly named QUERY() method of the /BOBF/IF_TRA_SERVICE_MANAGER instance. The query parameters are provided in the form of an internal table of type /BOBF/T_FRW_QUERY_SELPARAM. This table type has a similar look and feel to a range table or SELECT-OPTION. The results of the query are returned in a table of type /BOBF/T_FRW_KEY. This table contains the keys of the node rows that matched the query parameters. In our sample case, there should be only one match, so we simply return the first key in the list.

FIELD-SYMBOLS <ls_parameter> LIKE LINE OF lt_parameters. FIELD-SYMBOLS <ls_customer_key> LIKE LINE OF lt_customer_keys.

"Instantiate the test driver class: CREATE OBJECT lo_driver.

"Though we could conceivably lookup the customer using an SQL query, "the preferred method of selection is a BOPF query: APPEND INITIAL LINE TO lt_parameters ASSIGNING <ls_parameter>. <ls_parameter>-attribute_name =

Displaying Customer Records

With the query logic now in place, we now know which customer record to lookup. The question is, how do we retrieve it? For this task, we must use the

RETRIEVE() and RETRIEVE_BY_ASSOCIATION() methods provided by the /BOBF/IF_TRA_SERVICE_MANAGER instance. As simple as this sounds, the devil is in the details. Here, in addition to constructing the calls to the RETRIEVE*() methods, we must also dynamically define the result tables which will be used to store the results.

As you can see in the code excerpt below, we begin our search by accessing the customer ROOT node using the RETRIEVE() method. Here, the heavy lifting is performed by the GET_NODE_ROW() and GET_NODE_TABLE() helper methods. Looking at the implementation of the GET_NODE_TABLE() method, you can see how we’re using the /BOBF/IF_FRW_CONFIGURATION object reference to lookup the node’s metadata. This metadata provides us with the information we need to construct an internal table to house the results returned from the RETRIEVE() method. The GET_NODE_ROW() method then dynamically retrieves the record located at the index defined by the IV_INDEX parameter.

Within the DISPLAY_CUSTOMER() method, we get our hands on the results by performing a cast on the returned structure reference. From here, we can access the row attributes as per usual.

After the root node has been retrieved, we can traverse to the child nodes of the /BOBF/DEMO_CUSTOMER object using the RETRIEVE_BY_ASSOCIATION() method. Here, the process is basically the same. The primary difference is in the way we lookup the association metadata which is used to build the call to RETRIEVE_BY_ASSOCIATION(). Once again, we perform a cast on the returned structure reference and display the sub-node attributes from there.

Note: In this simple example, we didn’t bother to drill down to display the contents of the ROOT_LONG_TEXT node. However, if we had wanted to do so, we would have needed to create a separate service manager instance for the /BOBF/DEMO_TEXT_COLLECTION business object since the data within that node is defined by that delegated BO as opposed to the /BOBF/DEMO_CUSTOMER BO. Otherwise, the process is the same.

Modifying Customer Records

The process of modifying a customer record essentially combines logic from the display and create functions. The basic process is as follows:

First, we perform a query to find the target customer record.

Next, we use the RETRIEVE*() methods to retrieve the node rows we wish to modify. Using the returned structure references, we can modify the target attributes using simple assignment statements.

Finally, we collect the node row changes into the modification table that is fed into MODIFY() method provided by the /BOBF/IF_TRA_SERVICE_MANAGER instance.

The code excerpt below shows how the changes are carried out. Here, we’re simply updating the address string on the customer. Of course, we could have performed wholesale changes if we had wanted to.

Next Steps

I often find that the best way to learn a technology framework is to see how it plays out via code. At this level, we can clearly visualize the relationships between the various entities and see how they perform at runtime. Hopefully after reading this post, you should have a better understanding of how all the BOPF pieces fit together. In my next blog post, we’ll expand upon what we’ve learned and consider some more advanced features of the BOPF API.

Ah, I missed the long text part. Please find an updated version of the code at the download link above. I made some wholesale changes to the code so that it’s cleaner and more organized. Alas, the original demo was rather primitive. Let me know if you have any further questions. Thanks.

I have a question though. I have a requirement for my client for a monster “super query” against the EHHSS_INCIDENT business object which basically would allow them to query all Incidents by any combination of any selection criteria from any nodes!

I have already told them I think this is out of the question. However I want to at least be able to give them something. My main challenge is that it seems that Queries are attached to nodes, but what I really want is a cross-node query.

For example there is one node called “Persons involved” (table EHHSSD_INC_PINV) and another node called “Person Role” (table EHHSSD_INC_PROLE). This would allow me to query the persons involved in an Incident (selecting by John Smith for example) or the roles of people involved in an incident (eg Witness). But what it does not allow me to do is to query the Incidents where John Smith is a Witness. To do that I have to use a foreign key relationship in a GUID on EHHSSD_INC_PROLE to point to the DB_KEY on EHHSSD_INC_PINV.

So my main question is: Is it possible to do cross-node queries? If so how?

I thought about creating a database view as a join of the two tables, but then I don’t know how to hook this database view onto the BO processing framework and how to attach queries to it. Or is the way of having a transient structure which is a join of the two tables & somehow hook this into database retrieval & queries.

To answer your question: yes. For your specific use case(s), I think the approach would be to create custom queries. So, for example, if you want to create a query in which you pull all incidents where John Smith is a witness, I think you’d simply want to create a custom query against the ROOT node. Here, you’d have a data structure to capture the selection criteria (e.g. person name and role) and a custom class to implement the query logic using a SQL JOIN. A decent example of this would be the SELECT_BY_OSHA_CRIT query defined against the PERSON_INVOLVED node. Hope this helps.

What version of EHSM are you on? I’m looking at an EHSM 3.0 system with SP 4 installed and I don’t see a REVISION or ROLE node available in EHFND_CHEMICAL. These types of nodes are not uncommon to master data objects, so it wouldn’t surprise me that they were added in a later release of the software. However, as I can’t see the nodes myself, it’s hard to speculate what the error condition might be. At a glance, your code above looks to be correct…

One thing I might suggest is to look closely at the contents of EO_MESSAGE after you attempt to modify and/or save the BO. Here, I’d recommend scanning through the MT_MESSAGE table to find the error message in question and see if the NODE_KEY/VAL_KEY fields are populated. This might give you more of a clue about where the error condition is emanating from. Hope this helps.

Here is a very technical question about the mechanism whereby a number (like a customer number) gets turned into a GUID type key.

When I debug the SERVICE_MANAGER->QUERY method I see that a fuly dynamic SQL statement is being built up and then the database table queried using the customer number.

As there is no index on custmer number I would expect a full table scan to occur, and the performance to be dreadful. Yet this does not seem to be the case – performance is OK and the ST05 trace did not say “full table scan” but some Oracle gobbledegook I had not seen before.

Is there some black magic at work here to get around the fact you are selecting on a field where there is no index?

So am I correct in assuming that you’re testing with the /BOBF/DEMO_CUSTOMER business object demonstrated in this blog post? If so, I’m seeing that SAP has in fact created an index on the CUSTOMER_ID field in the table behind the ROOT node (/BOBF/DM_CST_HDR). Are you seeing something different on your end?

In general, I would say that there’s nothing real special going on with these node attribute queries. When you get past all of the dynamic code, the SQL queries executed by the BOPF runtime are basically OpenSQL as per usual.

Anyway, I hope this helps. If I’m off base with my analysis here, let me know a little more details about what you’re testing with and I’ll dig a little deeper.

As a test I had created my own object with a “number” field which is what the human in front of the computer would use to search for the object. An invoice number let us say.

As the primary key was the GUID and I deliberately did not put an index on the “number” then I expected the SQL trace to say “full table scan”.

I actually got something like “ROW STOPKEY” which I think means the database looks at every sinlge record in the table until it finds a match and then stops, which is in effect a full table scan.

I was just wondering if there was anything magic happening here, but it seems not.

This does throw into question the entire wisdom of having a database table with a GUID as the primary key – if you have an object where people are always going to search by number – invoices are a great example – then isn’t having two indexes – the primary key and the index on the number – just a doubling up of resources?

I know in HANA world this is not going to matter, but realistically most people are not going to be there any time soon.

OK, I’m with you now. You make a good point here on the wisdom of using GUIDs vs. semantic keys. In standalone environments, I frequently find this approach to be painful to work with (CRM comes to mind). In the dynamic world of the BOPF though, I think that the choice to use GUIDs actually makes a lot of sense. Being able to traverse from node to node by joining on PARENT.DB_KEY = CHILD.PARENT_KEY makes it very easy to build generic BO query frameworks where the performance is actually quite good. The primary overhead is when you hit the header table which would normally require an index on the semantic key. I suppose anytime you build a framework like this, there’s going to be some overhead, but in my mind, what they have here is pretty manageable. Anyway, my two cents.

I am new to BOPF, and trying to set up a condition in TM using BOPF. Standard SAP provide a BO /SCMTMS/SUPPLIER which is a Master data Object. I can read a Carrier in run time using this. There is another BO /SCMTMS/TOR, where I can read the data from a freight order for example Customer (in ConsigneeID field).

So when in SAP TM, I select a carrier to be assigned to a Freight Order, I can read Carrier separately using /SCMTMS/SUPPLIER and Customer from the FO separately under /SCMTMS/TOR. Once the carrier is assigned and FO is saved, I can read the carrier under /SCMTMS/TOR as well under TSP_ID but before that TSP_ID is blank.

My requirement is to read the “carrier to be assigned” under /SCMTMS/TOR before FO is saved, so that I can check a condition between customer and carrier before saving it. In other words I want to read the Partner value of /SCMTMS/SUPPLIER (Master data Object) in /SCMTMS/TOR in Business Process Object. Is this feasible? How to achieve this. Looking forward for your response. Thanks for the Help.

If my assumptions above are correct, I expect that you should be able to back track from the XBO association class to figure out how the two BOs are physically linked. If the carrier’s being identified before the save event occurs, I’d expect that you’d be able to get your hands on the foreign key to the carrier somewhere inside the /SCMTMS/TOR BO. From here, you may need to enhance/create a determination to preemptively fill the TSP_ID field using a SQL query based on the selected carrier key.

Again, I’m sort of flying blind here, so let me know if I’m off base or need further clarification. Hope this helps.

For the ease of understanding you can consider Freight order as a Sales Order and Carrier as a TSP (transport service provider partner which is not yet enter in the SO) and consignee as a ship to party.. Suppose you have saved the sales order with out the partner.. So you can see the Order number in VBAK table, you can see the Ship to party also in VBPA. But Since the carrier partner TSP is not yet assigned in the SO, it will be not be there in VBPA, although it exists as a master data in LFA1 table.

Now Consider LFA1 as /SCMTMS/SUPPLIER BO which is just a master data, and VBAK/PA as /SCMTMS/TOR BO which is the transaction data. When I pass the SO number in VBPA table, I can read ship to party, and when I pass the carrier number in LFA1, I can read the Carrier number from there.

Similarly I am using a data access determination using /SCMTMS/SUPPLIER (~LFA1) in a condition Cond1 and dad using /SCMTMS/TOR (~VBPA) in a condition Con2, when I pass the Carrier in cond1, I can read the carrier there and when I pass the freight order number in cond2, I can read ship to (consignee) in cond2, but since they are read in two different condition, I am not able to do some logical operations on them..

So I want to read both (Carrier to be assigned) and the Consignee under one condition. To do so I am trying to create a dad for /SCMTMS/SUPPLIER, and dad for /SCMTMS/TOR under same condition. Technically its not possible to so I am trying to read the /SCMTMS/SUPPLIER in /SCMTMS/TOR using some association and data crawler.

The TSP_ID field stores the carrier for a freight order and is directly under the ROOT node of TOR BO. But it can be read only once the Carrier is entered and freight order is saved with it./SCMTMS/SUPPLIER is a master data BO, and stores the Carrier under ROOT node in Partner field.

I tried to find an association in Trxn BOPF for /SCMTMS/TOR and I could find an association named BO_TSP_ROOT, But I am not sure if it links with /SCMTMS/SUPPLIER or not, don’t know how to check it.

I am looking for your help to find out more insight about association, and how to see what how two BO nodes associate.. and In case there in no association, is there any mechanism to read the Master data from a Master data node into the Business process Object in run time?

Sorry for such a lengthy post, I appreciate your help and patiently helping me out here.

This all makes logical sense. One question though: in your description above you mention that the carrier is not yet assigned to the freight order. Assuming that’s the case, I’m curious to understand when the condition you’re building is supposed to fire? Am I correct in assuming that you want this to start kicking in at the point when the carrier’s assigned but before the freight order’s saved?

Anyway, can you send some screenshots in BOPF of the /SCMTMS/TOR BO? Looking specifically for screenshots with the expanded node hierarchy, association definitions, etc. That would help point you in the right direction I think.

Actually its related to one Incompatibility setting, where when I select a Carrier and Freight Order, System checks the Carrier and Consignee (assigned in FO), and based on the condition result either allow or gives error. Standard SAP has given two separate condition for Carrier and FO, hence I have some limitation. I am trying to club both under one condition. My guess was that BO_TSP_ROOT can be one association, but somehow its not working as its not the Master data BO..

Can you also please send me a screenshot of the BO_TSP_ROOT association (highlighted above) when you double-click on it? In that definition, you should get a sense for how these two BOs are related. From here, perhaps we can backtrack and see if we can artificially build a linkage to satisfy your condition.

Yes, but what we need is the details around the association. For instance, is there an association class defined? On the Association Binding tab, what do the attribute bindings look like? To get where you want to go, you’ll need to figure out how to hoist the carrier ID up to a point where you can access it in your condition. So, you may have to create another determination to achieve this which utilizes similar logic to the association definition.

Given the way this association is defined, I’m thinking that you may have to get clever with this. I’m thinking something along the lines of the following:

Implement some enhancement logic to intercept the carrier assignment event and store the selected carrier ID in a shared memory object (which internally uses a hash table to associate the carrier ID with the corresponding FO).

Create a transient attribute on the root node of the freight order BO to expose the carrier ID.

Create a custom determination to populate the transient attribute with the carrier ID value from shared memory.

I think this should allow you to access the carrier ID from your condition record before the FO is saved. What do you think?

My thought with point #1 was to capture the event when the carrier is associated with the freight order (but before the FO is saved). Based on what you commented earlier (see below), I gathered that this was the gap you were struggling with: figuring out how to read the carrier ID in a condition before the FO is saved. The logic described above was intended to provide you with a separate field which makes it easy to link up the FO and carrier data from within the FO business object. Am I off base here?

…Once the carrier is assigned and FO is saved, I can read the carrier under /SCMTMS/TOR as well under TSP_ID but before that TSP_ID is blank…

The issue with your code is in the way you’re creating the PERSON_INVOLVED record. For both records, you’re mapping SY-UNAME to the PERSON_INVOLVED.ID field. To create separate records, you need to map different IDs for each distinct person. Here, you have three different types to choose from:

Employee Types (A + {pernr})

Business Partner Types (B + {bupa})

User Types (D + {user ID})

Without knowing a ton about your use case, it would seem that if all you have to go on is contact information, you probably will have to either use that information to look up one of the three person types listed above or create an ad hoc business partner on the fly. Regardless of the path you take, the resultant ID is what you would plug into the ID field. Do that, and I think you’re on the right track.

The reporting person would be created just like all the others. In this case though, you’d probably want to use the CL_EHFND_PARTY_PROXY class’ CONVERT_USER_NAME_TO_PARTY_KEY() method to convert SY-UNAME into an EHSM party key. Then, plug that key into the ID field and assign the reporting person role in the PERSON_ROLE node. Thanks.

For near misses, you can fill in the description field directly in the NEAR_MISS node using the DESC_TEXT field. Behind the scenes, BOPF determinations will copy the text into the subordinate node automagically.

For injury illness, the field is BP_DESC_TEXT in the INJURY_ILLNESS node.