FU BAPI_ALM_ORDER_MAINTAIN

____________________________________________________

Short Text

Process Maintenance/Service Order

Functionality

This Business Application Programming Interface (BAPI) is used to change maintenance orservice orders and their subobjects. The following objects of an order can be processed(restrictions are listed at the end of the documentation):

o Order header

o Partner

o User status

o Order operations

o Relationships

o Components

o Long texts for order header, operations, and components

o Settlement rules

o Object list

o Object list link

o Production resources/tools

o Outlines of a service package

o Services lines of a service package

o Limits of a service package

o Contract limits of a service package

o Estimated costs per value category

Function

Calling this BAPI once allows you to perform all operations. For this, the system supplies thefunction module with a method table containing the methods to be executed. The entries inthe method table refer to data records in the (optionally filled) data tables. All the methodsfrom the method table are executed. Alternatively, only subobjects of existing orders can bechanged, without changing the header.

You can process the transferred data with the Business Add-In (BAdI)IBAPI_ALM_ORD_MODIFY to, for example, merge data from the external system with datafrom the SAP system. The BAdI is called as soon as the transferred data is converted to theinternal formats. The checks then take place after this.

Note that after executing the method, you must execute the function module

______________________________________________________________SAP AG 1

SAP System______________________________________________________________

BAPI_TRANSACTION_COMMIT, so that the data is written to the database.

Structure of Method Table

o REFNUMBER Reference number for linking object method to attributesThe reference number is the line of the database that contains the corresponding data. The datatable is determined by the object type.

o OBJECTTYPE Object typeThe object type specifies which object from the order should be processed. The key words listedhere are not language-dependent and must be transferred exactly as they are. The followingobjects exist:

- HEADER Order header

- PARTNER Partner data

- USERSTATUS User status

- OPERATION Operation data

- RELATION Relationships

- COMPONENT Component

- TEXT Long texts

- SRULE Settlement rule

- OBJECTLIST Object list

- OLISTRELATION Object list link

- TASKLIST General maintenance task list

- PRT Production resources/tools

- SERVICEOUTLINE Service Package Outline

- SERVICELINE Service package service line

- SERVICELIMIT Service package limit

- SERVICECONTRACTLIMIT Service package contract limit

- ESTIMATEDCOST Estimated costs per value category

- (empty) General BAPI functions (Save)

o METHOD MethodThe methods with which the data is to be processed. The following functions exist:

- CREATE Create objects

- CREATETONOTIF Create for notification

- CHANGE Change objects

- DELETE Delete objects

- RELEASE Release

______________________________________________________________SAP AG 2

SAP System______________________________________________________________

- TECHNICALCOMPLETE Technically complete

- ATPCHECK Availability check

- CALCULATE Calculate

- SCHEDULE Schedule

- DELELTEDSEX Delete the status for external scheduling at operation level

- ADD Add (only possible for object TASKLIST)

- SAVE Save all data

- DIALOG Dialog call. See explanation below.

- TRACE Write trace file to the specified file on the front end

o OBJECTKEY SAP-external object keyThis key is for assigning the lower-level objects correctly to the corresponding objects, as thereis always just one key in the data table. The key must have the following structure:

- 1-12 Order numberWhen creating orders with internal number assignment, a reference number beginningwith % must be entered here. The BAPI then returns this number and the number actuallyassigned.

- 13-16 Operation number

- 17-20 Suboperation number

For relationships, the key is structured as follows:

- 1-12 Order number from

- 13-16 Operation number from

- 17-28 Order number to

- 29-32 Operation number to

The following methods are possible for the individual objects:

o HEADERCREATE, CHANGE, RELEASE, TECHNICALCOMPLETE, ATPCHECK, CALCUALTE,SCHEDULE, CREATETONOTIF

o OPERATIONCREATE, CHANGE, DELETE, DELETEDSEX

o PARTNER, RELATION, COMPONENT, USERSTATUS, TEXT, SRULE, OBJECTLIST,PRTCREATE, CHANGE, DELETE

o OLISTRELATIONCREATE, DELETE

o TASKLIST

______________________________________________________________SAP AG 3

SAP System______________________________________________________________

ADD

o ESTIMATEDCOSTCHANGE

o (empty)SAVE, DIALOG, TRACE

Data Tables and Update Tables

The objects have one or more data tables. For some objects you can specify which of thefields specified in the structure should be changed. For this, you must set the field in thecorresponding table to X as in the data table. If no update table is transferred, then onlythose fields are set that have a value that is not initial. This simplifies the transfer data.However, this means it is not possible to delete fields. If an update structure should only bespecified for some data records, the table with the update fields must nonetheless have thesame number of lines as the data table. The empty lines are then treated as if no updatestructure was transferred. The objects "Partner", "User Status", "Text", "Estimated Costsper Value Category", and "Task List" have no update tables. The whole data record isalways copied here.

References

The objects use the field REFNUMBER from the method table to refer to the lines in the datatable. Counting always begins with 1. In doing this, REFNUMBER also refers to the updatetable. However, in the method table there is a second reference to the higher-level object forsubobjects. The field OBJECTKEY must be filled with order number, operation number, andsuboperation number, as specified above. If subobjects of a newly created order should bechanged, then you must enter a temporary order number that must begin with %. Forexample, several orders may be numbered with %00000000001, %00000000002, and soon. For external number assignment, the external number must be specified.

The following objects have special handling for REFNUMBER:

o PartnerPartners have an order number in the data table. During processing of the method table, all thoseentries in the data table are processed that have an order number that is the same as that in theline to which the method refers. Thus, through just one entry in the method table, severalpartners can be changed.

o TextsTexts are composed of two tables. The first table (IT_TEXT) is made up of the header data ofthe text. Here you must specify the object and the first and last line of the text table (bothinclusive, counting from 1). This specifies a line segment in the text line table(IT_TEXT_LINES).

Special Features in Processing

The BAPI processes the transferred methods in a particular sequence, which need notcorrespond to the sequence in the methods table.

o Write trace file

o Change user status time 1

______________________________________________________________SAP AG 4

SAP System______________________________________________________________

o Delete objects (dependent first)

o Create new objects

o Change existing or newly created objects

o Change user status time 2

o Status change of order

o Save data

The methods are executed such that subobjects can also be assigned to newly createdobjects. For example, first the operations are created, and then the components. Long textscan also be created for the objects.

Components have an exceptional position. Components are created through the assignmentto an operation, that is, using the key order/operation/(item number). However, as this is notthe unique component key, you can only access the components to change them, deletethem, or add long texts by using the reservation number/item, which is only given aftersaving. This means that, for example, you cannot create a long text when you create thecomponent.

For settlement rules the following account assignment types are supported:

o Cost center

o Order

o WBS Element

o Asset

o G/L account

o Sales document

User status changes can take place at two different times. Time 1 is before the objectchanges, time 2 is after the object changes and before the status change of the system.These times should be defined in the transfer table in the CHANGE_EVENT field. The fielddocumentation contains the possible values.

The external scheduling is offered by the BAPI as a special function. The BAPI can set thedate field directly at the operation level, and select the operation with the status DSEX (Dateset by external system). This status prevents any further scheduling of the operation. Thetransferred dates are retained. For this, set the category X in the restriction categories.When reading the operation, this category is also returned, independent of the category ofrestriction set in the dialog. To delete the status, you can call up the method DELETEDSEXfor the object operation. The external scheduling cannot be influenced in dialog. All changesto the scheduling restrictions in the dialog are saved, but they are not relevant forscheduling as long as the status DSEX is active.

A SAVE or DIALOG method must be transferred in every call of the BAPI. Usually, the BAPIcall is thought of as a transaction. All data that is changed in the BAPI should also be savedimmediately to the database. The BAPI checks whether a SAVE method exists. Otherwise,it terminates processing. A test run of the BAPI consists of a standard call with SAVEmethod, followed by a BAPI_TRANSACTION_ROLLBACK. To call the BAPI without theSAVE method, for example, to realize dialog transactions, the BAPI can be called with the

______________________________________________________________SAP AG 5

SAP System______________________________________________________________

DIALOG method. This switches off the check for the SAVE method. The caller must thenensure that later either a SAVE method or a BAPI_TRANSACTION_ROLLBACK is called.

A BAPI_TRANSACTION_COMMIT without SAVE method terminates processing in theupdate to ensure that no inconsistent data is written to the database. The caller that calledthe BAPI does not receive any confirmation of the termination of the update in the targetsystem. This logic is necessary as the order data was flagged for updating withBAPI_TRANSACTION_COMMIT through the SAVE method. However, the statusinformation was already flagged for updating when the BAPI was called. ABAPI_TRANSACTION_COMMIT without SAVE method then just saves the statusinformation and would generate inconsistent orders, if the updating was not terminated.

The TRACE method is used to save an XML trace file on the front end under the file namespecified in the OBJECTKEY field. This file can only be written if the BAPI is called from thedialog, that is, from the SAP GUI. The file is not written if background processing is used,nor is it written if the call originates in a different system. This file can be used by SAP foranalysis purposes. SAP does not intend to use this data productively.

Customer Enhancement

The BAdI IBAPI_ALM_ORD_MODIFY can be used to change the transferred data. The BAdIis called up after the conversion of the transfer structure into the structures used internally.Additional data can be transferred via table EXTENSION_IN. The data is only check afterthis.

Refurbishment Order

BAPI BAPI_ALM_ORDER_MAINTAIN also supports the creation and change of refurbishmentorders.

Refurbishment-order-specific header data, item (component) data, and serial number data isalways created and updated together with the order header data even though it is passed tothe BAPI separately.

In order to support refurbishment-order-specific data, the interface of the BAPI has beenenhanced by the following table parameters:

o IT_REFORDER_ITEM (BAPI_REFORDER_ITEM_I)

o IT_REFORDER_ITEM_UP (BAPI_REFORDER_ITEM_UP)

o IT_REFORDER_SERNO_OLIST_INS (BAPI_REFORDER_SERNO_OLIST_I)

o IT_REFORDER_SERNO_OLIST_DEL (BAPI_REFORDER_SERNO_OLIST_I)

Refurbishment order item data (IT_REFORDER_ITEM) is mandatory for the creation ofrefurbishment orders. A refurbishment order cannot be created without this data. If serialnumbers are to be assigned to the refurbishment order (object HEADER, methodCREATE/CHANGE), they must also be passed using the parameterIT_REFORDER_SERNO_OLIST_INS. If a serial number is to be unassigned from the orderduring an update of the order (object HEADER, method CHANGE), the parameterIT_REFORDER_SERNO_OLIST_DEL must be passed to the BAPI. Only existing serialnumbers can be assigned to the refurbishment order.

______________________________________________________________SAP AG 6

SAP System______________________________________________________________

Refurbishment-order-specific parameters are always processed together with the orderheader data. This means that if the refurbishment order is created or updated, the orderheader data structures must be provided by the calling application. Even if the header dataitself must not be updated, at least the order number of the refurbishment order beingupdated must be provided in the order header structures:

o IT_HEADER (BAPI_ALM_ORDER_HEADERS_I)

o IT_HEADER_UP (BAPI_ALM_ORDER_HEADERS_I_UP)

In all cases, the update and creation of the data of the first component in the refurbishmentorder (the refurbishment order item), as well as the assignment and deassignment of serialnumbers, is triggered by providing the HEADER object with the corresponding methodCREATE or CHANGE in the method table

The HEADER object for a refurbishment order is also responsible for creating and updatingthe refurbishment-order-specific data, for example, plant from/to; storage location from/to,batch from/to, valuation type from/to). There may be several serial numbers assigned to asingle refurbishment order, so the parameter table must always contain the order number towhich the serial number is assigned.

The data of the first component (refurbishment order item) is always created with the orderheader data. In order to be able to create this data, the HEADER function must be specifiedin the method table.

The data of the first component can be updated either with the header data (objectHEADER, method CHANGE) or separately by specifying the function component update(object COMPONENT, method CHANGE) in the method table. If the data of the firstcomponent is updated with the order header data, then the structures for the header datamust also be passed to the BAPI interface (the order number at least must be specified). Ifboth methods of updating the component data are used simultaneously in the method table,then the refurbishment order item data is updated with the header data.

When the refurbishment order is created, the first operation is generated automatically. Ifthis generated data needs to be changed, an update must be triggered in the method table.The first operation must be generated for refurbishment orders (unlike standard orders) inorder to make it possible to create the data of the first component with the refurbishmentorder header data.

The BAdI BADI_REFORDER_BAPI_MESG allows the user to suppress some messages thatare raised during the creation or update of a refurbishment order. These messages areshown as warning messages when the back-end transaction is executed, so this BAdIprovides the user with the flexibility to control the message type of these messages in theBAPI.

______________________________________________________________SAP AG 7

SAP System______________________________________________________________

Restrictions and Limitations

o The first operation cannot be created as an external operation.

o The first refurbishment order operation must not be created manually by passing therelevant data through the method table.

o When more than one order is processed at once, the same serial number must not beassigned to several orders.

o The same serial number can be assigned to another order only if the first order hasbeen successfully committed to the database table.

o Only existing serial numbers can be assigned to the refurbishment order.

o The first generated refurbishment order component cannot be updated within theexecution of the same BAPI call.

DIMP-Specific Features

o An order can be created from a notification using the CREATETONOTIF method forthe object type HEADER.

o A notification can be created for the order.

o The notification type has to passed within the parameter IT_HEADER(BAPI_ALM_ORDER_HEADER_I-NOTIF_TYPE)

o A notification can be separated from the order.

o The notification type (NOTIF_TYPE) must be empty in the IT_HEADER, and thecorresponding update flag (NOTIF_TYPE) must be set in the update parameterIT_HEADER_UP.

o An object list can be maintained for the refurbishment order.

o DIMP-specific fields can be maintained at the header level:

- Special stock is determined automatically from the equipment or material/serial numberstock data if the refurbishment order is being created for a piece of equipment(BAPI_ALM_ORDER_HEADER_I-EQUIPMENT) or a material/serial number(BAPI_ALM_ORDER_HEADER_I-SERIALNO andBAPI_ALM_ORDER_HEADER_I-MATERIAL have to be specified in tableIT_HEADER)

- Sales order, sales item (BAPI_ALM_ORDER_HEADER_I-SALES_ORD andBAPI_ALM_ORDER_HEADER_I-S_ORD_ITEM must be specified in the tableIT_HEADER)

o DIMP-specific fields can be changed at the component level. In particular, the specialstock indicator can be set for the component.

Example

The following examples illustrate usage:

______________________________________________________________SAP AG 8

SAP System______________________________________________________________

Creation of an order

OBJECTKEY should be filled with a temporary key. The BAPI returns this key together withthe assigned order number in the return table ET_NUMBERS. The order number in theHEADER table should also be filled with the number. For external number assignment, theexternal number should be specified. The update structure can be transferred if necessary.

Methods tableREFNUMBER OBJECTTYPE METHOD OBJECTKEY1 HEADER CREATE %00000000001

IT_HEADERORDERID ORDER_TYPE PLANPLANT ...%00000000001 PM01 1000 ...

Creation of an order with operation and long text

Methods tableREFNUMBER OBJECTTYPE METHOD OBJECTKEY1 HEADER CREATE %000000000011 OPERATION CREATE %000000000011 TEXT CREATE %000000000010010

IT_HEADERORDERID ORDER_TYPE PLANPLANT ...%00000000001 PM01 1000 ...

IT_OPERATIONACTIVITY SUB_ACTIVITY CONTROL_KEY WRK_CNTR ...10 PM01 MECHANIK ...

IT_TEXTACTIVITY ... TEXTSTART TEXTEND10 ... 1 2

IT_TEXT_LINESTDFORMAT TDLINE * Long text for operation 10, line 1 * Line 2 of the long text

Creation of the refurbishment order header data with one serial number assigned (operation and firstcomponent are created automatically):

Methods tableREFNUMBER OBJECTTYPE METHOD OBJECTKEY1 HEADER CREATE %000000000011 SAVE

IT_HEADERORDERID ORDER_TYPE PLANPLANT ...%00000000001 PM04 0001 ...

IT_REFORDER_ITEM

______________________________________________________________SAP AG 9

SAP System______________________________________________________________

ORDERID REQUIREMENT_QUANTITY PLANT_TO PLANT_FROM ...%00000000001 3 0001 0002 ...

IT_ REFORDER_SERNO_OLIST_INSORDERID SERIALNO UII%00000000001 SN01

Creation of the refurbishment order data, changing the first operation data, adding the secondoperation and second component:

Methods tableREFNUMBER OBJECTTYPE METHOD OBJECTKEY1 HEADER CREATE %000000000011 OPERATION CHANGE %0000000000100102 OPERATION CREATE %000000000011 COMPONENT CREATE %000000000011 SAVE

IT_HEADERORDERID ORDER_TYPE PLANPLANT ...%00000000001 PM04 0001 ...

IT_REFORDER_ITEMORDERID REQUIREMENT_QUANTITY PLANT_TO PLANT_FROM ...%00000000001 3 0001 0002 ...

IT_OPERATIONACTIVITY SUB_ACTIVITY ... DESCRIPTION ..0009 ... Update of 1st Operation ..0020 ... New 2nd Operation ..

IT_OPERATION_UPACTIVITY SUB_ACTIVITY ... DESCRIPTION ..X ... X ..

IT_COMPONENTRESERV_NO RES_ITEM PLANT MATERIAL ... 0001 MN_01 ...

Update of the data of the refurbishment order#s first component from header data (recommended):

Methods tableREFNUMBER OBJECTTYPE METHOD OBJECTKEY1 HEADER CHANGE 0000040000011 SAVE

IT_HEADERORDERID ORDER_TYPE PLANPLANT ...000004000001 ...

______________________________________________________________SAP AG 10

SAP System______________________________________________________________

IT_HEADER_UPORDERID ORDER_TYPE PLANPLANT ...000004000001 ...

IT_REFORDER_ITEMORDERID REQUIREMENT_QUANTITY PLANT_TO PLANT_FROM ...000004000001 6 9999 ...

IT_REFORDER_ITEM_UPORDERID REQUIREMENT_QUANTITY PLANT_TO PLANT_FROM ...000004000001 X X ...

IT_REFORDER_SERNO_OLIST_DELORDERID SERIALNO UII000004000001 SN01

Notes

Using the BAPI to process the order data cannot support all the functions of the transaction. Thisapplies in particular to the following functions:

Order header data

o Notification data cannot be processed with the order BAPI, even if the settings inCustomizing are such that the orders and notifications can be maintained on onescreen. However, the system will create a notification with the order if this isspecified in the Customizing settings.

o Permits cannot be processed.

o The order addresses cannot be processed.

o Individual partner addresses cannot be maintained.

Order functions

o Printing the papers is not possible.

o Locking and unlocking the order is not possible.

o Accepting and rejecting quotations is not possible.

o Business completion is not possible.

o Flagging for deletion is not possible.

o The log cannot be displayed.

o User default values are not used.

o The field selection is not checked.

o The customer exits/BAdIs are not executed completely.

o Joint ventures are not supported.

______________________________________________________________SAP AG 11

SAP System______________________________________________________________

o Funds management is not supported.

o Investment orders are not supported.

o No integration of service products with task lists is possible if configuration data hasto be maintained.

o No integration of configurable service products is possible if configuration data has tobe manually maintained.

o Assignment of sales document items with service products in accordance with theaforementioned conditions.

Operation data

o A change of the control key in the operation is not possible, if this leads to a changeof the processing type (internal/external processing).

o User status change not possible.

o Production resources and tools cannot be processed.

o Service lines cannot be processed.

o Integration of task lists with configurations is not supported, since manualmaintenance of the characteristic valuations would be performed in the dialog.

o Automatic linking of operations with object list is not supported. If a new operation isto be generated for a new object list entry, you must do this by creating a newoperation in the corresponding BAPI method and linking to the object list entry usingthe object OLISTRELATION.

Component data

o User status change not possible.

o BOM data cannot be processed.

o The delivery address cannot be processed.

Further information

See also the documentation for the individual transfer tables.

Parameters

IV_MMSRV_EXTERNAL_MAINTENACEIT_METHODSIT_HEADERIT_HEADER_UPIT_HEADER_SRVIT_HEADER_SRV_UPIT_USERSTATUSIT_PARTNERIT_PARTNER_UPIT_OPERATIONIT_OPERATION_UPIT_RELATION

______________________________________________________________SAP AG 12

SAP System______________________________________________________________

IT_RELATION_UPIT_COMPONENTIT_COMPONENT_UPIT_OBJECTLISTIT_OBJECTLIST_UPIT_OLIST_RELATIONIT_TEXTIT_TEXT_LINESIT_SRULEIT_SRULE_UPIT_TASKLISTSEXTENSION_INRETURNET_NUMBERSIT_REFORDER_ITEMIT_REFORDER_ITEM_UPIT_REFORDER_SERNO_OLIST_INSIT_REFORDER_SERNO_OLIST_DELIT_PRTIT_PRT_UPIT_REFORDER_OPERATIONIT_SERVICEOUTLINEIT_SERVICEOUTLINE_UPIT_SERVICELINESIT_SERVICELINES_UPIT_SERVICELIMITIT_SERVICELIMIT_UPIT_SERVICECONTRACTLIMITSIT_SERVICECONTRACTLIMITS_UPET_NOTIFICATION_NUMBERSIT_PERMITIT_PERMIT_UPIT_PERMIT_ISSUEIT_ESTIMATED_COSTS

Exceptions

Function Group

IBAPI_ALM_ORDER

______________________________________________________________SAP AG 13

SAP System______________________________________________________________