Purpose

The purpose of this little series of blog posts is to provide an orientation to working with equipment addresses in customer developed programs. In prior blog posts, we looked at how addresses are managed. Now in this blog post, we look at how to create a piece of equipment and assign an address to it.

This is the fourth blog post in the series, which has the following structure.

Similar to the prior blog posts, we will continue with a generous sprinkling of code snippets.

What are we seeking to achieve?

Our mission is pretty simple – you have been asked to create a piece of equipment with some address details. At the end, you are successful, if the equipment has an address number and the address can be seen in the any of the standard SAP transaction.

Given what you already know from prior posts, you will need the equipment number to properly maintain the ownership and where used references of the address when using the services of the Business Address. Then you also need somehow to link the address with the equipment.

This implies a sequence of

1. Create the equipment
2. Create the address
3. Assign the address to the equipment
4. Transaction Commit

Unfortunately, I’m unaware of any one Business API that supports all of these steps – so to achieve the outcome we are looking for, we will need to put these steps together in our own transactional API.

Step 1 – Creation of the equipment

Your first thought might be to explore the Business API for creating an equipment. Looks promising. We can create the equipment and get the equipment number back.

call function 'BAPI_EQUI_CREATE'

Note that the interface for the BAPI has a field in the structure DATA_GENERAL called READ_ADRNR. Whilst it is part of the input parameters, any value supplied is ignored. The type of DATA_GENERAL is used in lots of different contexts – and when an equipment is read, the field will contain the assigned address number, if existing.

After calling this function, subject to validations, an equipment number is provided. Note – the equipment is not yet written to the database – that will occur only when we signal the end of the transaction. At this point in time, we haven’t got to the end of our “transaction” – we want to do some more steps yet – so no commit yet.

Step 2 – Create the address

We are creating the equipment and want to insert a brand new individual address for the equipment.

Assuming we set up the address reference details correctly using the equipment number, we use the functions from Address Services – proceeding as follows:

 CALL FUNCTION 'ADDR_INSERT'
 CALL FUNCTION 'ADDR_NUMBER_GET'
 CALL FUNCTION 'ADDR_MEMORY_SAVE'

The next post in this blog will provide more details for the preparation of ADDR_INSERT.

We now have the equipment, the address reference, but we still haven’t made the address assignment known to Plant Maintenance. We haven’t got to the end of our “transaction” – we want to do some more steps yet – so no commit yet.

Step 3 – Assigning the address

Now this is the step where many come to grief. How do we tell the equipment that this address is associated with it? Address services know – the reference details – but the data model of Plant Maintenance doesn’t know (yet).

Here is how I go about it:

data equipment_attributes type itob.

call function 'ITOB_EQUIPMENT_READ_SINGLE'
     exporting
       i_objnr        = equipment      " Yep! This is the equipment number

equipment_attributes-adrnr = my_new_address_number.

call function 'ITOB_EQUIPMENT_MODIFY_SINGLE'
     exporting
       i_filter_data  = abap_off
       i_write_buffer = abap_true
       i_post_buffer  = abap_true        
       i_object_rec   = equipment_attributes

The effect of the above steps are to provide address reference to the equipment processing.

The BAPIs of the equipment family manage their state using functions of the package ITOB and hence the state at the end of BAPI_EQUI_CREATE is known and managed by ITOB. The function ITOB_EQUIPMENT_READ_SINGLE has read the internal state and the MODIFY_SINGLE has updated the internal state.

Step 4: Commit the changes

and now finally we signify the end of our “transaction”.

call function 'BAPI_TRANSACTION_COMMIT'
     exporting
       wait = abap_true.

Now lots of update processes are initiated (turn on update debugging to have a look!) and most importantly, the end results is the equipment, the address and the address reference will be written to the various tables.

Mission accomplished!

Nevertheless, at this point, you might have some questions

Is there a similar approach in SAP delivered code?

For the same approach in SAP standard code, albeit with some more decoration, you might explore

CL_EAMS_BO_EQUI->SET_EQUI_ADDRESS( )

Why not just write the address number in ILOA?

I’ve seen lots of customer and partner code that updates the ADRNR (address number) in table ILOA directly. I don’t like this approach, particularly when it is used in the context of BAPI or SAP dialog transactions because the database is likely to be updated from the buffers of the BAPIs upon commit work – and sometimes with delay in update tasks.

I think it is cleaner and easier to work with the equipment/functional location (Technical Object)  buffers.

What about inheritance and installation?

When an equipment is installed into a functional location, there is the possibility that the address of the equipment will be inherited from the superior object and thereafter referenced. Many technical objects can reference the same address.

If you want to install your piece of equipment and you don’t want the address to be overwritten, be sure to correctly maintain the inheritance flags of the function BAPI_EQUI_INSTALL.

    " From the documentation of the data element INHERITANCE_FLAG
    " E means "Do not inherit" 

    " Here do not inherit the address from the installation location".
    inheritance_flags-adrnr = 'E'.

    installation-funcloc = location_internal.
    installation-inst_date = sy-datum.
    installation-inst_time = sy-uzeit.

    call function 'BAPI_EQUI_INSTALL'
      exporting
        equipment         = me->key   " Number of Equipment to be Installed
        data_install      = installation  " Installation Data for Equipment
        inheritance_flags = inheritance_flags

Summary

Phew! Again lots of little snippets of code – more like a cook-book to look up than a novel to read!

From this fourth blog post, you should now have a better understanding of to create equipment and assign an address to the equipment from customer developed programs. The next and last post will be more of an appendix – how to create an address for equipment in address management.