Equipment Address Management - Creating Equipment with an address

[AB]

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.

1. Equipment Address Management - introduction


2. Equipment Address Management - a closer look


3. Equipment Address Management - reading and searching for addresses


4. Equipment Address Management - creating Equipment with an address


5. Equipment Address Management - creating an address for equipment

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, when 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 so the equipment knows of the address.

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 -potentially 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'

 

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.

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 be supplied the address number of the equipment, if existing.

Step 2 - Create the address

We have created 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 the equipment. And since 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 knows - via the reference details - but the equipment itslef 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.

You should know that the BAPIs of the equipment family manage state. The changes are not written directly to the database, but maintained in internal tables waiting until either a ROLLBACK WORK or COMMIT WORK to occur.

The internal state is managed using functions of the package ITOB. The state at the end of BAPI_EQUI_CREATE is known and managed by ITOB. The function ITOB_EQUIPMENT_READ_SINGLE reads the internal state and the MODIFY_SINGLE updates the internal state.

Step 4: Commit the changes

and now finally we signify the end of our "transaction". If we are happy, we commit our changes.

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 result is a new piece of equipment with an address.

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.