SAP ERP HR Agent

The ERP system in which the application is to be installed must have a release level of 6.0 or higher. The installation procedure assumes that the clients 000 and 001 are at least similar to the configuration that is delivered by SAP. The installation procedure also assumes that the Human Resources (HR) component in the client into which the application is to be installed is configured according to your needs.

To prevent conflicts with other applications, you must check to make sure that the name space required by SAPAgent (/sie/dirx…​) is not already in use. This should not normally be the case, because the name space is reserved for this application.

Use the repository browser to check the namespace in the ABAP workbench. If the name space contains objects, do not proceed with the installation until you have determined the source and purpose of these objects.

The Workbench import transports are indispensable for the installation and include the program logic and data structures.

The Customizing import transports are only required for a new installation. If customizing has already been performed, you should omit this step.

The imports must be performed in the following sequence:

Note: The workbench import must be performed once for a system. The customizing import must be performed for the actual client or clients that use the agent.

To import each of the transports:

After the transport has been imported, check the result code. Depending on the environment, a return code of 0 or 4 is okay. Other return codes (e.g., 8 or 12) indicate severe problems – the installation is not successful.

It is recommended that you create new users for the maintenance and execution of SAPAgent and that you maintain these users with the necessary authorizations. The user selected for SAPAgent execution also must be authorized to read the HR master data, to write into the file system of the application server and to execute external applications on the application server (if enabled during customization).

In order to simplify this process two pre-defined roles are included in the customizing data of the SAPAgent. See below for more information about roles.

The following figure shows the Selections area of the vertical selections dialog box.

Each selection criteria field is displayed on a separate line. Click in any selection criteria field (or press F4) to display a list of the entries that are allowed for the field.

Click on the Further selections button to add more selection criteria. The Personnel number field is a mandatory selection field, and you must always supply a range. Selection criteria fields that have no values entered in the lower portion of a range are not used for limiting the selection.

The following figure shows the Other attributes area of the vertical selections dialog.

The next sections describe the fields of the Other attributes area.

The Objects and Reporting period sections enables you to specify selection criteria which the agent then uses to determine which set of OM data is read. These selection “screens” are the standard SAP report selection screens used in HR management. It contains a series of selection fields and buttons which are described in the SAP manuals. For further information see

http://help.sap.com/erp2005_ehp_06/helpdata/EN/1b/16a7375de78668e10000009b38f889/frameset.htm

Plan version, Object type and at least one Object Id are mandatory fields. The object Id is used as a starting point. Object type defines what kind of OM objects are to be exported.

The Evaluation path field is an optional selection field and is used to navigate to the result set of the objects. You can only use evaluation paths that are defined in the ERP system. If you cannot find a suitable evaluation path, you must use the ERP system to define a new path. You can set an evaluation depth. The agent evaluates the objects to export along an evaluation path. With setting the depth you can reduce the number of evaluated objects. For example, the path O-O recursively describes the predecessor organizational unit. If you are interest just in the superior unit set the evaluation depth to 2.

Selection criteria fields that have no values entered in the lower portion of a range are not used for limiting the selection.

There are two definitions, one for a person export and the other for an OM object export.

For both definitions the following input parameters are passed to the method:

CONFIGURATION
Specifies the configuration identifier (id=number).

CONTENT
A structure of strings that matches the actual configuration. Here is an example, if you use the default configuration:

In a BAdI implementation you can either specify the content in a structure as given in the example above or you access the structure by specifying offset and length.

EVENT
Is a flag specifying the time when the exit is called while processing each object (a person or an OM object) in an export. Valid values for this flag are:

Additionally to the parameters above the following input parameter is passed to the method for a person export:

PERNR
Specifies the personnel structure.

The following input parameter is passed to the method for an OM object export:

OBJEC
Specifies the OM object structure.

The method delivers the following output parameter:

STATUS

Specifies whether an object is excluded from the export (value 1) or not (all values not equal 1).

Of course there may be several configurations using exclusion. However, you should activate only one implementation. The configuration class and the configuration identifier specify the actual activated configuration.

Here is an example for a person export method:

Here is an example for an OM object export method:

There are two definitions: one for a person export and the other for an OM object export.

For both definitions, the following input parameters are passed to the method:

CONFIGURATION
Specifies the configuration identifier (id=number).

TAG NAME
Specifies the tag name.

FIELD NAME
This parameter is not used and therefore is always empty.

FIELD VALUE
The value that the agent computes before calling the exit.

Additionally to the parameters above the following input parameter is passed to the method for a person export:

PERNR
Specifies the personnel structure.

The following input parameter is passed to the method for an OM object export:

OBJEC
Specifies the OM object structure.

The method delivers the following output parameter:

RETVALUE
Returns the computed user-defined tag value.

There may be several user-defined tags per configuration and several configurations using user-defined tags. However, you should activate only one implementation. The implementation class, configuration identifier, and the tag name specify the current activated configuration and tags.

Here is an example for a user-defined tag in a person export method:

Here is an example for a user-defined tag in an OM object export method:

To enable a tag as a user exit, specify a X in the Use Exit field in the Change View "Tag-Names": Details dialog box. (See the section "Horizontal (Attribute) Selection" above for details.) The agent evaluates the Infotype and Field name fields of the tag before calling the exit. It passes the resulting value to the exit.

This functionality is provided by an additional BAdI:

BAdI Definition: /SIE/DIRXAG_ADDPERNR

Method: GET_ADD_PERSONS

Parameters

This method accepts the following parameters:

On a call of an implementation of the above BAdI, the agent supplies the configuration number (so that the BAdI can distinguish between different configurations), the PERNR object (NOT only the personnel number) of the actual (real) employee and the key date for which the employee’s data is being extracted.

The BAdI implementation is then expected to return a table of generated personnel numbers (Type PERNR_D) in parameter VIRTUAL_PERSONS_PERNR and a corresponding table of virtual employees with each entry of the same structure as MASK in parameter VIRTUAL_PERSONS_CONTENT.

Example Coding

Assuming the following TAG configuration:

Here is the corresponding BAdI implementation:

Example Output

Based on the BAdI implementation sample but with all fields of the two virtual employees filled, this is the resulting export file:

You can see that the two "virtual" persons 90000001 and 90000002 have been inserted between the "real" persons 00001001 and 00001002 with the values assigned to them in the BAdI implementation. The DN has also been constructed by these values.

Output Transformation via Reference Tables

Looking at the definition of tags for this configuration, the definition of tag "OU" defines a value replacement via the organizational unit’s text table (T527X):

This is also performed for virtual persons, so just the key has to be inserted into the virtual person; the SAPAgent automatically transforms the key to a text value via the reference definition. The corresponding coding in the BAdI for virtual person 90000001’s OU is:

The output file shows the transformed value:

Delta Processing

The virtual person records are subject to the SAPAgent’s delta processing.

If in the example above, the BAdI implementation would return a different value for any tag:

A MODIFY record would be created:

Tags with Multiple Values

Tags can be defined to return a list of values instead of a single value:

In these cases, the BAdI implementation must deal with field symbols and operations to internal tables instead of data elements (note the usage of field symbol <fs2t> instead of <fs2> :

Definition:

Assigning the internal table and inserting data:

The corresponding output looks like this:

This case study provides an example how to set up an exit for a person selection. Perform the following steps:

This case study provides an example how to set up an exit for user-defined tag evaluation of an OM object. Perform the following steps:

This case study provides an example how to set up an exit for defining a user-defined tag to report a user’s hire date. It is implemented using the same procedure as case study 2 above.

The code below demonstrates the exit implementation to fill the tag "HIRE" in configuration "1". The hire-semantic is customer specific and therefore this example may not work in every installation.

The administrator must enter the values for the Infotype (value 0000) and Field name fields (value MASSN). The agent evaluates these values. The retrieved value is not used in this exit.

This is used in the "tag" details configuration, where it allows to maintain an evaluation path to go from an employee’s OM relevant information (common are ORGEH or PLANS in infotype 0001) to the details of that OM object.

Example:

Assume in a standard PA export the following definition of tag POS:

Then, for the selected employee’s every infotype 0001 record, the content of the position (field PLANS) is taken and OM’s evaluation path ‘S_UP’ is used to define the owning organizational unit of this position, and from this organizational unit’s object definition (infotype 1000) the description (field STEXT) is returned.

Yielding in an output like:

It can be seen that all the related OUs of the position of the employee are listed. If only the root is needed, then ‘Only max level’ should be specified; if only the direct OU of the position is needed, then a ‘Technical depth’ of 2 should be specified in the tag’s configuration.

For a SAPAgent export defined on above OU hierarchy this would be a valid "tag" configuration:

Especially take note, when looking at the details of for example the OMOBJID tag, it is not necessary (that is it would not work as expected) to mark OM specifications additionally here:

Shown below is a valid "attributes" configuration:

It uses the (common) "O-S-P" evaluation path (selectable via the F4 help in the SAPAgent’s tag detail configuration) to travel from a given OU via (even multiple sub OUs) to a position and then to the associated employee:

However, you may wonder why you get the same (one) employee multiple (2) times in your export file. This is so because it will be found beneath organizational units myroot and mysubroot1.

Therefore a more elegant way would be to restrict only to the root(s) of the organizational units:

The complete export would then look like this: