Sapass

 Simplify SAP R/3 development with Excel VBA/VB RFC  
Home> Bapi>EmployeeTrip



Index

EmployeeTrip

EmployeeTrip


The business object Employee - trip is an employee business
trip. A trip represents an employee's change of location, including the
journeys to and from the destination, so that he or she can temporarily carry out tasks away from his or her usual place of work.


Structure
A trip contains several trip facts, which consist mainly of data on
trip times, trip destinations, and trip expenses. The data is used to calculate reimbursement amounts.

Each trip has exactly one status which characterizes the respective
stage of its "life cycle": applied for; carried out; accounted, etc.

Individual specifications concerning the allocation of costs to cost
centers, projects, manufacturing orders, etc. can be made for a trip or for the individual trip facts.

Example

Employee: John White
Trip duration: from January 3 1996 10 a.m. to January 5 1996 10.15 p.m.

Main destination: ABC & Co, Detroit, USA
Trip type - statutory: business trip

Trip expenses reimbursement type: accommodations - individual
meals - per diem

travel costs - flat rate
Distance: 678 miles
Individual statement: hotel bill - US-$400


11-Dec-2005


Methods

Available Methods


  • Approve : Approve trip [ BAPI_TRIP_APPROVE ]
  • Cancel : Cancel trip [ BAPI_TRIP_CANCEL ]
  • CollectMileage : Determination of employee trip segments [ BAPI_TRIP_COLLECT_MILEAGE ]
  • CreateFromData : Create EmployeeTrip with CallTransaction on PR01 [ BAPI_TRIP_CREATE_FROM_DATA ]
  • CreateFromDataWeekly : Creation of weekly report (PR04) [ BAPI_TRIP_REPORT_CREATE ]
  • Delete : Delete trip [ BAPI_TRIP_DELETE ]
  • ExistenceCheck : Check existence of object [ BAPI_TRIP_EXISTENCECHECK ]
  • GetDetails : Print detail tables for trip (receipt entry) [ BAPI_TRIP_GET_DETAILS ]
  • GetDetailsWeekly : Detail tables for weekly report (output of tables) [ BAPI_TRIP_REPORT_GET_DATA ]
  • GetExpenseForm : Standard travel expense form [ BAPI_TRIP_GET_FORM ]
  • GetExpenseForm_HTML : Standard travel expense form as HTML tables [ BAPI_TRIP_GET_FORM_HTML ]
  • GetList : List of trips for employee [ BAPI_TRIP_CHECK_STATUS ]
  • GetOptions : Import personal data and travel expense tables [ BAPI_TRIP_GET_OPTIONS ]
  • GetOptionsWeekly : Create local workspace for ReportCreate (print tables) [ BAPI_TRIP_REPORT_INIT ]
  • GetStatus : Establish status of trip [ BAPI_TRIP_CHECK_STATUS ]
  • SetOnHold : Set Trip Status to "On Hold" [ BAPI_TRIP_SET_ON_HOLD ]

11-Dec-2005


Approve

Approve


Using the method EmployeeTrip.Approve, you can approve anindividual emloyee trip, if you have the authorization to do so.

As parameter, the complete qualifying key for the trip to be approved only must be specified. It consists of the
EmployeeNumber
and the TripNumber.

The status of the method call can be determined from the return parameter Return after the method has been performed.


11-Dec-2005


Cancel

Cancel


Using the method EmployeeTrip.Cancel, you can cancel individualemployee trips, if you have the authorization to do so.

As parameter, the complete qualifying key for the employee trip to be canceled only must be specified. The key consists of the
EmployeeNumber and the TripNumber.

The status of the method call can be determined from the return parameter Return after the method has been performed.


11-Dec-2005


CollectMileage

CollectMileage


IMPORTING:
This method returns per personnel number the miles or kilometers traveled by an employee within a time interval.
Transfer parameter: EMPLOYEENUMBER FROM_DATE TO_DATE.

There is the additional option to limit the search to a certain vehicle type and class.

Transfer parameter: VEH_TYPE VEH_CLASS.

EXPORTING:
The RETURN structure indicates the success (value 'S') or failure (value 'E') of the search.

RETURN (STRUCTURE BAPIRETURN)
TYPE Message type: S success, E error

CODE Message code
MESSAGE Message text
LOG_NO Application log: log number
LOG_MSG_NO Application log: sequential number

TABLES:
The miles/kilometers determined are returned to the table MILEAGE with exact dates.


If no legs of trips are found to meet the selection conditions, thetable MILEAGE remains empty and the RETURN structure contains a success message.


11-Dec-2005


CreateFromData

CreateFromData


The method EmployeeTrip.CreateFromData is used to createemployee trips in the Travel Management Module of the R/3 System.

The following import parameters are available:

  • EmployeeNumber (personnel number of the employee for whom an employee trip is to be created)

  • Framedata (Framework data for the employee trip)
  • Status (the status of the employee trip, which is to be set)
  • Furthermore, the following tables are available as import parameters:

  • Receipts (trip receipts)

  • Addinfo (additional receipt information)
  • Text (additional trip information, receipt editor)
  • Mileage (miles/kms distribution)
  • Stopover (trip stopovers)
  • Deductions (trip deductions)

  • CostDist_Trp (cost distribution for entire trip)
  • CostDist_Stop (cost distribution for stopovers)
  • CostDist_Rece (cost distribution for receipts)
  • CostDist_Mile (cost distribution for miles/kms distribution)

  • If the method call runs without errors, the trip number assigned by R/3 is returned to the TripNumber field. (Internal trip number assignment is a precondition for this function.)

    The status of the method call can be determined from the return parameter Return
    after the method has been performed.

    Further Information

    Information on the fields in the individual tables can be found in structure documentation or the Data Dictionary.


    11-Dec-2005


    CreateFromDataWeekly

    CreateFromDataWeekly


    Using the method EmployeeTrip.CreateFromWeeklyReport, simplifiedweekly reports for trip costs recording (transaction PR04) can be created.

    The data required for this can be transferred in tables Week, Receipts,Addinfo
    and Text.
    The parameter Startdate specifies the beginning date of theweekly report here (Take parameter FDW of feature TRVPA into accountbecause the first day of the week is specified via this parameter!)
    If the weekly report is created without any errors, the trip number assigned by R/3 is returned in the TripNumber
    field (internal trip number assignment is a requirement here). Otherwise, errors whichoccur during performance of data import (from dialog) are returned in the parameter Return.

    Technical details:

    The weekly report was created via a call transaction for transaction
    PR01. The call transaction guarantees that weekly reports created inthis way are consistent, since all entry checks are performed within the call transaction.
    The structure of the individual transfer tables can be found in the Data Dictionary. Please note that the fields in table
    Addinfo
    can require compulsory fields or initial values depending on the expense type (1:1 relation!) used in tableReceipts.

    Further Information

    See also the documentation on function module BAPI_TRIP_REPORT_INIT and
    the structures BAPITRWEEK, BAPITRVREC, BAPITRADDI and BAPITRTEXT.


    11-Dec-2005


    Delete

    Delete


    Using the method EmployeeTrip.Delete, you can delete individualemployee trips, as long as they have not yet been posted and you have the relevant authorization.

    As parameter, the complete qualifying key for the employee trip to be canceled only must be specified. The key consists of the
    EmployeeNumber and the TripNumber.

    The status of the method call can be determined from the return parameter Return after the method has been performed.

    Notes

    If the employee trip has already been posted, deletions can only be carried out under certain conditions.

    You can only delete changes which have been made since the last posting was carried out.

    The only way a trip that has already been posted can be canceled is to use the method EmployeeTrip.Cancel.


    11-Dec-2005


    ExistenceCheck

    ExistenceCheck


    The method EmployeeTrip.ExistenceCheck is used to see if a trip that isspecified by means of the key EmployeeNumber and TripNumber already exists.

    If the employee trip specified exists in the system, the returnparameter Return-Type has the value S, otherwise it has value E. In the
    latter case, there is a relevant error text in the Return-Message field.


    11-Dec-2005


    GetDetails

    GetDetails


    The method EmployeeTrip.GetDetails is used to obtain all of the details of an employee trip.

    As parameter, the complete qualifying key of the employee trip only must be specified. The key consists of the EmployeeNumber and the TripNumber.
    The Language
    parameter is optional and indicates the language for the referenced table entries, if they differ from the logonlanguage of the calling program.

    Trip details include:

  • Framework data of the trip (Framedata)
  • Status of the trip (Status)

  • Receipts (Receipts)
  • Additional receipt information (Addinfo)
  • Trip text (Text)
  • Miles/Kms distribution (Mileage)
  • Stopovers (Stopover)

  • Deductions (Deductions)
  • Cost distribution for entire trip (CostDist_Trip)
  • Cost distribution for stopovers (CostDist_Stop)
  • Cost distribtution for receipts (CostDist_Rece)

  • Cost distribution for miles/kms distribution (CostDist_Mile)
  • Furthermore, additional information on the employee trip is specified.The additional trip information refers to the different amounts for the trip (Amounts
    ), as well as employee information (Emp_Info).

    The status of the method call can be determined from the return parameter Return after the method has been performed.

    Further Information

    Information on the fields of the individual tables can be found in structure documentation or the Data Dictionary.


    11-Dec-2005


    GetDetailsWeekly

    GetDetailsWeekly


    The method EmployeeTrip.GetDetailsWeekly is used to return alltables belonging to a trip costs weekly report which was created via the method EmployeeTrip.CreateFromDataWeekly in R/3.
    In addition, the structuresEmp_Info and Amounts are
    filled. The structure Emp_Info contains information on the employee, the structure Amounts contains different amounts of trip costsaccounting.

    The individual fields of the structures can be found in the Data Dictionary.


    11-Dec-2005


    GetExpenseForm

    GetExpenseForm


    The EmployeeTrip.GetExpenseForm method is used to obtain the trip costs standard form as an ASCII table.

    The report RPRTEF00 form (Trip costs standard form) is created and returned as an ASCII table.
    Selection of trips takes place via the personnel number (EmployeeNumber) and the trip number (TripNumber
    .
    Using the parameter SET_PRINT_FLAG, the indicators of the selectedtrips, if they have already gone through accounting, can be set to 'trip printed'.
    After the method has been successfully performed, the selected trips (their trip costs forms) can be found in table Tripform
    as ASCII tables. In this table, the relevant keys for the employee trips are specified in the initial position.

    After the method has been performed, the status of the method call can be found in the return parameter RETURN.

    Usage as function module:
    This function module is used to return the trip costs form (report
    RPRTEF00) as an internal table. You can also have the trip costs formoutput directly on the screen (interactively), if the parameter DISPLAY_FORM is set to 'X'.
    All other parameters correspond with those of the method call.


    11-Dec-2005


    GetExpenseForm_HTML

    GetExpenseForm_HTML


    When the method EmployeeTrip.GetExpenseForm_HTML is called, thestandard form for trip costs accounting is returned as a HTML table. Ifthe method is correctly performed (see parameter RETURN), the output table (TRIPFORM_HTML
    ) contains the list output of the standard trip costs form (reportRPRTEF00) in several HTML tables,formated according to the report's output format.
    These HTML tables can easily be pasted into your Intranet page.
    If you want to create a separate page for the form (e.g. using a CGI
    script) you only need to make the following additions in order to obtain a complete HTML page:
    Before outputting the lines of table TRIPFORM_HTML, set the header andthe beginning of the main section of the HTML page (using for example"<HTML><HEAD><TITLE> Trip costs accounting </TITLE></HEAD> <BODY>" and
    after output of all lines in table TRIPFORM_HTML, set the end tag ("</BODY></HTML>").

    Notes

    Occasionally the headings in the HTML tables do not correspond with thetable columns. The tables in the form also differ in width due to the HTML table structure.



    11-Dec-2005


    GetList

    GetList


    Via the method EmployeeTrip.GetStatus, the status of an individual tripis returned, provided it exists in the R/3 System for the key specified(EmployeeNumber, TripNumber). At the same time, the return structure AMOUNTS is filled.

    Via the method EmployeeTrip.GetList, all of an employee's trips with
    trip beginning between DEPARTURE_FROM and DEPARTURE_TO are returned inthe structure TRIPS. If you would like to obtain the amounts for thedifferent trips at the same time, the parameter CALCULATEAMOUNTS mustbe set to 'X'. Please take the performance aspects (see below) into consideration, however.


    Both of the above methods also have the return value RETURN, which provides an exact error message in the event of errors.

    Usage as a function module:

    Using the function module BAPI_TRIP_CHECK_STATUS you can determine


  • the status of an employee's individual trip (transfer parameter EMPLOYEENUMBER und TRIPNUMBER)
    or
  • the status of more than one trip for an employee within a time interval(transfer parameters EMPLOYEENUMBER, DEPARTURE_FROM and DEPARTURE_TO).

    The parameters TRIPNUMBER or DEPARTURE_FROM and DEPARTURE_TO are to bechosen. If the parameter TRIPNUMBER is transferred, only one trip isselected. If the parameters DEPARTURE_FROM and DEPARTURE_TO are chosen,all trips for the employee with departures between these dates are returned.

    The return of the selected trips takes place via the table TRIPS. Inaddition, the various subtotals and totals for the selected trips (seestructure BAPITRVSUM) are contained in the table AMOUNTS. Thecalculation of these amounts can be switched on (='X') or off (=SPACE)
    using the switch CALCULATEAMOUNTS. For performance reasons, this switchshould, however, only be used for small time intervals or individual trips because the calculation of trip amounts can be verytime-consuming.
  • Examples


    11-Dec-2005


    GetOptions

    GetOptions


    The method EmployeeTrip.GetOptions designates all tables andparameters which could be required for creating a trip using transaction PR01 or PR05.

    The import parameter EmployeeNumber determines the personnelnumber for which the local work space is to be created, Date
    determines the date for which the table entries should be read and the Language parameter determines the language for the table entries.
    By means of the import parameter Select_Last, you can determine whether the values in tables Countries and Currencies are
    read from the Customizing tables (Select_Last = Space), or whether thevalues in these tables are determined from the last trips (Select_Last = "X"). In the latter case, parameter Scan_X_Trips determines the number of trips to be searched.
    The table Cost_Objects
    is only filled if the Select_Last parameter has the value "X" and, in this case, contains the last costobjects posted to by the employee.
    The Select_Last parameter especially gives you the possibilityto prepare a kind of short F4-Help for these fields, since the complete country and currency tables can be very lengthy.


    The status of the method call can be determined from the return parameter Return after the method has been performed.

    Notes

    Most of the return tables are Travel Management Customizing tables. Although it would be possible to read these tables via
    BAPI F4-Help, some of these tables also contain additional authorizationfields that are employee-specific. Consequently, the use of generalBAPI-F4-Help would lead to many more table entries and make calling the method EmployeeTrip.CreateFromData
    more difficult.

    Further Information

    For more information, especially concerning individual table fields,see the structure documentation for the tables DEFAULTS, EXPENSE_TYPESand COST_OBJECTS or the relevant structures for the tables in the Data Dictionary.


    11-Dec-2005


    GetOptionsWeekly

    GetOptionsWeekly


    Using the method EmployeeTrip.GetOptionsWeekly you can obtainall tables and default values needed to create a simple weekly report (transaction PR04).

    The import parameter EmployeeNumber determines the personnelnumber for which the lokal workspace is to be created, Date
    indicates a date within the weekly report to be created, Language indicates the language of the table entries.
    The parameter Check_Overlap is used to switch verification on
    (='X') or off (=Space) as to whether, for the date transferred, a weekly report already exists or not.
    Using Sel_Coun
    andSel_Curr, the additional tables T706O_DAT, or TCURR_DAT can be filled, if needed.

    The export table Emp_Info contains information on the specified personnel number, table Defaults
    contains the parameters

  • Firstday (refers to first day of weekly report, determined fromfeature TRVPA, entry FDW as date, referring to the week specified by DATE).
  • CCCParam (TRVPA, switch CCC; see documentation on feature TRVPA ),

  • Rec_F_PD (TRVCT, F line, position 1; see docu. on feature TRVCT),
  • Rec_U_PD (TRVCT, U line, position 1; see above)
  • Rec_V_PD (TRVCT, V line, position 1; see above.)
  • MWAUS (table T706D, MWAUS) and

  • Mileage_PD (reimbursement amount per mile/km traveled for firstmile/km driven in the week in employee's local currency; if miles/kmsaccumulation is not active, this rate is valid for the whole week, otherwise it can differ!)
  • Table T706B_DAT contains the trip expense types valid for this
    personnel number. This is a section of table T706B with the respectivefields required for the receipt entry check. The SC***fields in thisstructure represent a link to the entry fields in the "Additional receipt info" dialog in trip costs recording available for this
    receipt. These fields can have the following characteristics:

  • "+" : mandatory field
  • "-" : invisible field, therefore not active
  • "." : ready for entries
  • SPACE: field displayed only
  • Table T706O_DAT contains the values in table T706O (countries and regions) for this employee.
    T706O_DAT
    contains all currencies stored in the system (tables TCURC and TCURT), together with the entries from the conversion tablefor currencies (TCURR) and the decimal points for currencies (TCURX).
    The export parameter RETURN, finally, supplies information concerning the results of the method called.



    11-Dec-2005


    GetStatus

    GetStatus


    Via the method EmployeeTrip.GetStatus, the status of an individual tripis returned, provided it exists in the R/3 System for the key specified(EmployeeNumber, TripNumber). At the same time, the return structure AMOUNTS is filled.

    Via the method EmployeeTrip.GetList, all of an employee's trips with
    trip beginning between DEPARTURE_FROM and DEPARTURE_TO are returned inthe structure TRIPS. If you would like to obtain the amounts for thedifferent trips at the same time, the parameter CALCULATEAMOUNTS mustbe set to 'X'. Please take the performance aspects (see below) into consideration, however.


    Both of the above methods also have the return value RETURN, which provides an exact error message in the event of errors.

    Usage as a function module:

    Using the function module BAPI_TRIP_CHECK_STATUS you can determine


  • the status of an employee's individual trip (transfer parameter EMPLOYEENUMBER und TRIPNUMBER)
    or
  • the status of more than one trip for an employee within a time interval(transfer parameters EMPLOYEENUMBER, DEPARTURE_FROM and DEPARTURE_TO).

    The parameters TRIPNUMBER or DEPARTURE_FROM and DEPARTURE_TO are to bechosen. If the parameter TRIPNUMBER is transferred, only one trip isselected. If the parameters DEPARTURE_FROM and DEPARTURE_TO are chosen,all trips for the employee with departures between these dates are returned.

    The return of the selected trips takes place via the table TRIPS. Inaddition, the various subtotals and totals for the selected trips (seestructure BAPITRVSUM) are contained in the table AMOUNTS. Thecalculation of these amounts can be switched on (='X') or off (=SPACE)
    using the switch CALCULATEAMOUNTS. For performance reasons, this switchshould, however, only be used for small time intervals or individual trips because the calculation of trip amounts can be verytime-consuming.
  • Examples


    11-Dec-2005


    SetOnHold

    SetOnHold


    Using the method EmployeeTrip.SetOnHold, you can set anindividual employee trip to status "Request waiting for documents" or"Trip waiting for documents", if you have the necessary authorization to do so.
    The status is set according to whether it is a question of a travel request or a trip.


    As parameter, the complete qualifying key of the employee trip to be approved only must be specified, which is made up of theEmployeeNumber and the TripNumber.

    The return parameter Return can be determined from the status of
    the method call after the method has been performed.


    11-Dec-2005