SAP HR Organizational Charting Interface€¦ · display the hierarchical data in a graphic presentation. The interface utilizes the functionality provided by the Object and Data

SAP HR Organizational Charting Interface (HR-OCI)

Version 1.0 Partner Integration Guide

SAP HR Organizational Charting Interface (HR-OCI) - Partner Integration Guide

PURPOSE ............................................................................................................4

TARGET AUDIENCE ...........................................................................................4

SYSTEM REQUIREMENTS .................................................................................4

GLOSSARY..........................................................................................................5 SAP Enterprise Portal ..................................................................................................... 5 Business Package ............................................................................................................ 5 Business Package for Manager Self-Service (SAP MSS) .............................................. 5 iView............................................................................................................................... 5 Object and Data Provider (OADP) ................................................................................. 5 View ID........................................................................................................................... 5 Focused Object................................................................................................................ 6

CERTIFICATION ..................................................................................................6

BUSINESS SCENARIOS .....................................................................................7

Scenario 1: On-line data extraction: via vendor ............................................................ 7

Scenario 2: Off-line data extraction – via vendor .......................................................... 8

Scenario 3: On-line data extraction – via SAP............................................................... 9

AUTHENTICATION HANDLING ........................................................................10

EXTERNAL APPLICATION LAUNCH ...............................................................10

Launching options........................................................................................................... 10 Launching link ...................................................................................................... 10 Launching iView................................................................................................... 11

Launching Parameters ................................................................................................... 11 Launching link ...................................................................................................... 11 Launching iView................................................................................................... 11

Usage of launching parameters...................................................................................... 12

Sample View ID............................................................................................................... 13

Version 1.0, September 2005 2


INTERFACE STRUCTURE ................................................................................14

The FM HCM_GET_ORGSTRUCTURE_AS_XML ................................................. 14 Input parameters............................................................................................................ 16 Output file ..................................................................................................................... 19

SAP XML Schema for Organizational Charting......................................................... 20 The element <OrganizationalStructureQueryResponse> ............................................. 21 The complex element <OrganizationalEntity>............................................................. 21 The element <KeyDescription>.................................................................................... 21 The group <DefaultSet> ............................................................................................... 22 The element < Child> ....................................................Error! Bookmark not defined. The element < AdditionalData > .................................................................................. 22



Purpose The SAP HR Organizational Charting Interface (HR-OCI) is an interface to the SAP system for external organizational charting applications. This document describes the interface, which allows an external system to extract SAP HR Organizational Management objects and relationships and display the hierarchical data in a graphic presentation. The interface utilizes the functionality provided by the Object and Data Provider (OADP) and SAP Query to extract the desired data from SAP Organizational Management and SAP Personnel Administration. Note: The interface only supports one-way data extraction from the SAP system to an external organizational charting application. It cannot be used to transport organizational data from an external application to the SAP system. This document contains the technical specifications needed for a third-party vendor to develop a connection to the standard SAP HR Organizational Charting Interface (HR-OCI) Version 1.0.

Target Audience This document is intended for use by third-party vendors who wish to integrate their organizational charting application with the mySAP ERP Human Capital Management product and the SAP Enterprise Portal. The primary use for the HR-OCI is to display organizational charts within the SAP Manager Self-Service (SAP MSS) solution. Therefore, the certification procedure is done with a portal installation with an SAP MSS implementation. In principle, the HR-OCI is an interface related to SAP Organizational Management; it uses the customizing tables from the SAP MSS solution (that is OADP tables).

System Requirements In order to use the SAP HR Organizational Charting Interface (HR-OCI) with the Business Package for SAP Manager Self-Service (SAP MSS), you must meet the following requirements:

You must be using SAP HR Organizational Management on R/3 Release 4.6C or higher; You must be using the R/3 Web Plug-In Release 2004.1; (If you are using ERP2005, you

do not need the plug-in.) You must be running the Business Package for Manager Self-Service, BP 50.4 or higher

on the SAP Enterprise Portal using JDK version 1.3.1 or higher. The certification process in this document pertains to the integration with the HR Organizational Charting Interface using SAP MSS.



Glossary

SAP Enterprise Portal The SAP Enterprise Portal allows an enterprise to unify information, applications, and services on a browser-based interface. The SAP Enterprise Portal consists of a portal platform, a content management platform, and a business intelligence platform. For additional information on the SAP Enterprise Portal, please refer to the documentation in the SAP Knowledge Warehouse under the path SAP NetWeaver → SAP Enterprise Portal → EP5.0 SP 5/English.

Business Package A business package is a set of pre-assembled content for completing a business task. Business packages provide out-of-the-box portal applications that can be easily modified to suit a customer's needs.

Business Package for Manager Self-Service (SAP MSS) The Business Package for Manager Self-Service (SAP MSS) is a product offering for the SAP Enterprise Portal. SAP MSS is designed for employees who perform management tasks at the operational level. It serves as a single point of access to data and information that helps managers to make the right decisions at the right time. The SAP MSS is comprised of the components My Budget and My Staff. My Budget supports managers in fulfilling their cost and budgeting responsibilities. My Staff supports managers in their administrative and planning tasks in Human Resources.

iView An iView (also known as a Service) is a portal content component that retrieves data from applications, stored documents or the Internet, and displays it in the enterprise portal.

Object and Data Provider (OADP) The Object and Data Provider is a tool that enables you to display structures in the form of a list or a hierarchy, providing that these structures were created and maintained in Organizational Management. It also allows you to display additional information on the displayed objects as the contents of a column. For more details, please see the Configuration Guide for OADP in Documentation section of the SAP Service Marketplace (Manager Self-Service → Documentation → Technical Documentation → Configuration Guides → Configuration Guides 50.3 – My Staff). Detailed information can also be found in the IMG documentation. In the Plug-In System, choose Integration with Other mySAP.com Components → Business Packages/Functional Packages → Manager Self-Service → Object and Data Provider. One part of the OADP customizing is used to define the evaluation path, which specifies the relationship paths to retrieve the required objects. In addition, the OADP tool is used to define the depth, which specifies the numbers of depth levels downward or upward to retrieve the required objects.

View ID The View ID technically defines which objects, attributes, and hierarchical information of the organizational structure are extracted from the backend SAP system. The OADP tool is used to configure the individual View ID.


http://help.sap.com/saphelp_ep50sp5/helpdata/en/start.htm

http://service.sap.com/~form/sapnet?_SHORTKEY=01100035870000498748&_OBJECT=011000358700003001722003E


Focused Object A focused object is an organizational object (for example organizational unit, position, job, or person) that is placed at the top of the organizational chart displayed by the vendor’s application.

Certification To enable a third party organizational charting application to work with the SAP system, the third party vendor must be able to communicate with the SAP HR-OCI. Once this has been completed, the SAP Integration and Certification Center (ICC) will test the communication link between the SAP OCI and the third party application. If the communication passes the certification process, SAP will certify the third party’s connection. SAP supports the following three HR-OCI integration scenarios:

On-line data extraction – via vendor Off-line data extraction – via vendor On-line data extraction – via SAP

Select the links above for more information on these integration scenarios. The certification process requires the successful completion of the following two steps:

1. Given specified sets of calling parameters (View ID, query scenario, object type, object ID, plan variant, begin date, end data, and key date), the organizational charting application must be able to call the HR-OCI to produce the correct sets of XML data.

2. Using an XML document produced from the HR-OCI, the organizational charting

application must be able to process the XML data and correctly represent the organizational management data graphically.

Through the ICC, SAP will supply multiple sets of Organization Management test data in a backend SAP system. SAP will also provide test cases with sets of calling parameters along with the corresponding expected output. The organizational charting application must satisfy one or more test cases in order to be certified for each scenario. In the first two integration scenarios, both steps of the process must be performed successfully in order to produce the organizational chart correctly. In the case of the third scenario (On-line data extraction – via SAP), only the second certification step is necessary for a successful completion. However, to pass the certification process, both of the certification steps must be completed successfully. The certification process does not require the vendor to support all of the three scenarios. The application vendor can choose to support one or more of the scenarios, based on the customer's requirements. SAP does not deliver the certified partner’s software or an Application Programming Interface (API) developed to communicate with the SAP HR-OCI. This software must be purchased from, and delivered by, one of our certified partners.



Business Scenarios The HR OCI is designed to work in the following three scenarios within SAP MSS.

Scenario 1: On-line data extraction: via vendor A manager — utilizing Manager Self Service (MSS) in the SAP Enterprise Portal — selects an organizational chart display link in the browser, which launches the external organizational charting application. The third party application connects to the SAP HR-OCI through a remote-enabled function module in the SAP system (HR + Web Plug-In) and extracts organizational data, such as organizational units, positions, and employee data. Using this data, the third party application builds an organizational chart and displays it in a graphic presentation.

© SAP AG 2002, XML Interface OrgCharting, GBU HCM, SAP AG p.2

SAP XML data stream

Organizational Chart Application

SAP EPMSS

link

SAP R/3 HR

APIRFC function module

1

2

3x+2

x+1

SAP 3rd Party Vendor

launch

data request

data response

navigate upwards

navigate downwards

x

Scenario 1: On-line data extraction – via vendor

Figure 1: Scenario 1 On-line data extraction – via vendor



Scenario 2: Off-line data extraction – via vendor A manager — utilizing Manager Self Service (MSS) in the SAP Enterprise Portal — selects an organizational chart display link in the browser, which launches the external organizational charting application. The third party organizational charting application extracts the entire organizational data from the SAP backend system using the HR-OCI interface. The application then publishes the organizational chart as a web resource for the customer (for example an HTML page on the customer's intranet). Having a web resource available as a link in Manager Self Service, a user can launch the published organizational chart.


SAP XML data stream


SAP EPMSS

link

SAP R/3 HR

x

1

2


launch

data request

data response

navigate upwards

navigate downwards

x+1

Scenario 2: Off-line data extraction – via vendor


3 publish chart


Figure 2: Scenario 2 Off-line data extraction – via vendor



Scenario 3: On-line data extraction – via SAP A manager – utilizing Manager Self Service (MSS) in the SAP Enterprise Portal – selects an organizational chart display link in the browser, which will initiate data extraction from the SAP system. The extracted data is then passed via the XML based interface to the third party organizational charting application. Using this data, the third party application builds an organizational chart for display in a graphic representation. Note that in each integration scenario, the organizational charting application is launched from the SAP Enterprise Portal. The external charting application will be launched with a set of URL parameters described below. In each of the above scenarios, it is necessary that the organizational charting application be able to receive a URL request, that is, be web-enabled.



SAP XML data stream

SAP EPMSS

iView

SAP R/3 HR2

3


data request

data response

navigate upwards

navigate downwards

x

Scenario 3: On-line data extraction – via SAP


link

1 internal call

4 launch

SAP XML data stream

Figure 3: Scenario 3 On-line data extraction – via SAP



Authentication Handling HR data displayed in an organizational charting application may be sensitive or confidential. In these cases, it may be necessary to identify and authenticate a user before the extracted data is displayed. In the integration scenarios, there are two steps in the process that potentially require some type of user authentication:

Logging on from the SAP Enterprise Portal to the external organizational charting application (optional)

Logging on from the external organizational charting application to the SAP backend system (mandatory)

For example, in Scenario 1, a link in the SAP Enterprise Portal launches an organizational charting application that may require a user authentication. The organizational charting application subsequently retrieves the organizational data from the SAP system, which requires a separate user authentication. Customers should be able to configure their scenario so that a separate login is not required for each of the above steps. To facilitate the user authentication process to the external charting application, the launching link or iView will pass the portal user ID in the launching parameters to the organizational charting application. In addition to the portal user, a mapped user and password can also be passed in the launch parameters: In the User Management configuration in the SAP Enterprise Portal, a customer can define a Data Source for the organizational charting application. In the defined Data Source, the customer can configure the mapping from the portal user to an associated user and password. The mapped user and password can be passed to the organizational charting application when it is launched. Alternatively, the vendor can enable their application for Single Sign-On (SSO). For additional information, please refer to the documentation on Authentication in the SAP Enterprise Portal in the SAP Help Portal under: SAP Enterprise Portal Documentation → Administration Guide → Security → Authentication.. For additional information on user authentication and security, please refer to the Enterprise Portal Administration Guide in the SAP Library... In Scenarios 1 and 2, the organizational charting application calls the HR-OCI to retrieve the desired data, where user authentication to the SAP system is required. User authentication to an SAP system can be accomplished using the standard procedures to enable communications between SAP and external systems through remote function calls (RFC). SSO can also be used to facilitate the user authentication process. For additional information, please contact the SAP Integration and Certification Center (ICC) through the SAP Service Marketplace (alias: ICC).

External Application Launch

Launching options Below are two options that can be used to launch the external organizational charting application. The option used will depend upon which of the above scenarios is implemented.

Launching link A link can be pre-defined in the Portal using Content Administration. If this option is chosen, the customer will need to define and configure the link. Scenario 1 and 2 can be launched using this option.


http://help.sap.com/sapdocu/netweaver/portals/ep50sp5/helpdata/en/eb/01783ab66811d5993900508b6b8b11/content.htm

http://help.sap.com/sapdocu/core/47x200/HELPDATA/EN/d2/cb3f2e455611d189710000e8322d00/content.htm

http://help.sap.com/sapdocu/core/47x200/HELPDATA/EN/d2/cb3f2e455611d189710000e8322d00/content.htm


Launching iView SAP will provide an iView within the SAP MSS Business Package. This iView provides a list of links, from which a user can launch the organizational charting application. The links can be pre-configured, specifying the launching parameters mentioned below. Scenario 1 and 2 can be launched using this option. Scenario 3 requires this iView.

Launching Parameters Depending on the launching option, the following parameters can be passed to the organizational charting application upon its launch.

Launching link o User ID

The User ID specifies the Portal user ID used to log in to SAP MSS or any mapped user ID from the Portal user ID. This can be customized using the User Management functionality in the SAP Enterprise Portal. The customer will be required to define and configure the user ID that is passed. A separate chapter with information about User Management is available in the SAP Enterprise Portal Administration Guide.

Launching iView From the launching iView, the following set of parameters will be passed:

o User ID

Same as above

o Mapped user ID The mapped user from the configured Data Source (see Authentication section)

o Mapped user password The password from the configured Data Source (see Authentication section)

o View ID The View ID (ref. Glossary) is used to specify the set of Organizational Management objects that are to be extracted from the backend SAP system.

o Query scenario The Query Scenario is used to define a set of SAP Queries, which can be used to extract additional information associated with the Organizational Management objects. For example, if the organizational object is a person, additional information could include the person's name, e-mail address, or phone number.

o Default focused object

The default focused object (ref. Glossary) specifies the Organizational Management object that placed at the top of the organizational chart. Separate parameters will be used to pass the object type and the object ID.

o Integration Scenario

The integration scenario parameter is used to indicate which of the three scenarios is being used.

1. On-line data extraction – via vendor; 2. Off-line data extraction – via vendor; 3. On-line data extraction – via SAP


http://help.sap.com/saphelp_ep50sp5/helpdata/en/38/76bd3b6e74d708e10000000a11402f/frameset.htm


o Destination The destination specifies the JCo Destination that is configured in the SAP Enterprise Portal.

o XML interface data In Scenario 3, the iView will extract the Organizational Management data using the Organizational Charting Interface and pass the data to the organizational charting application in this field. Note: In Scenarios 1 and 2, this parameter will have the value zero.

Usage of launching parameters The launching parameters can be used to populate certain calling parameters of the remote function module of the Organization Charting Interface. The formal URL parameters are as follows:

portaluserid: The portal user ID.

mappeduser: The mapped user.

mappedpassword: The mapped password.

viewid: The View ID.

queryscenario: The SAP Query Scenario.

objecttype: The object type of the default focused object.

objectid: The object ID of the default focused object.

integscenario: The integration scenario that is used (1, 2, or 3).

destination: The configured JCo destination.

xmldata: The XML data stream from the OCI with the Organizational Charting data (see integration scenario 3).

For further details, refer to the section on the input parameters of the function module HCM_GET_ORGSTRUCTURE_AS_XML.



Sample View ID SAP will deliver the sample View ID OCIMIN. The sample View ID defines the following types of object, relationships, and attributes: Object types:

O – organizational unit S – position P – person US - user

Relationship types:

A$$$ – Root organizational object (no parent) A002 – Reports (line) to (for organizational units) B002 – Is a line supervisor of (for organizational units) A003 – Belongs to (for positions) B003 – Incorporates (for positions) A008 – Holder (for persons holding positions) A012 – Manages B012 – Is Managed

Objects and Attributes:

Organizational units (object type 'O') o Object name (technical name: P1000-STEXT) o Description/General description (P1002-SUBTY) o Department (P1003-ABTEL) o Staff (P1003-STABS) o Company code (P1008-BUKRS) o Business area (P1008-GSBER) o Personnel area (P1008-PERSA) o Personnel subarea (P1008-BTRTL) o Controlling area (P1008-KOKRS)

Positions (object type 'S')

o Object name (P1000-STEXT) o Description/General description (P1002-SUBTY) o Department (P1003-ABTEL) o Staff (P1003-STABS) o Vacancy (SYHR_T_P1007_VACAN) o Position filled (SYHR_T_P1007_STATUS) o Company code (P1008-BUKRS) o Business area (P1008-GSBER) o Personnel area (P1008-PERSA) o Personnel subarea (P1008-BTRTL) o Controlling area (P1008-KOKRS) o Hours per week (P1011-WKAVG) o Obsolete (P1014-REDUN)

Person (object type 'P')

o Company code (P0001-BURKS) o Personnel area (P0001-WERKS) o Personnel subarea (P0001-BTRTL)



o Business area (P0001-GSBER) o Cost center (P0001-KOSTL) o Employee group (P0001-PERSG) o Employee subgroup (P0001-PERSK) o Payroll area (P0001-ABKRS) o First name (P0002-VORNA) o Last name (P0002-NACHN) o Work schedule rule (P0007-SCHKZ) o Part-time employee (P0007-TEILK) o Employment percentage (P0007-EMPCT) o Hours per week (P0007-WOSTD)

The information defined in the View ID OCIMIN encompasses the minimal data set that needs to be interpreted by the organizational charting application. Additional information on the various object types, relationships, and attributes that are part of SAP Organization Management and SAP Personnel Administration can be found in the SAP Library. In the XML schema section, you can see how the information will be presented in the XML document returned from the interface. For example, the <Relation> element of the <DefaultSet> group may hold one of the values list above in the Relationship Type list. Note: the attributes above are given in the <KeyDescription>/<AdditionalData> elements. The <KeyDescription> element describes the semantics of the attributes. The corresponding value for the attribute is contained in the <Key> and <Value> elements of the <AdditionalData> element. Therefore, it is not necessary for a vendor to know the SAP technical names of the attributes above (since it can be derived from the XML document itself); however, we provide the list above for reference purposes. The list above represents the minimal set of object types, relationships, and attributes. A customer may choose to configure their system so that the HR-OCI returns object types, relationship, and attributes that are not listed above. In that case, the third party vendor will need to work with the customer to determine how the information should be parsed and displayed.

Interface Structure The HR-OCI represents a standard SAP Remote Function Call (RFC) interface that returns an XML document. The XML document produced by the interface conforms to the SAP XML Schema for Organizational Charting. Data is extracted from the SAP system using the function module HCM_GET_ORGSTRUCTURE_AS_XML. This remote-enabled function module uses the Object and Data Provider (OADP) tool and SAP Query functionality provided in the SAP system. The customer must configure these tools and set any necessary system authorizations in order to call the function module. The customizing details are addressed in a separate document: (Configuration Guide for the HR Organizational Charting Interface (HR-OCI).)

The FM HCM_GET_ORGSTRUCTURE_AS_XML The function module HCM_GET_ORGSTRUCTURE_AS_XML is called within the SAP HR-OCI with the user and View-ID as calling parameters. The View-ID refers to a view within the SAP Manager Self-Service (SAP MSS) Business Package. A view corresponds to a collection of hierarchical data displayed as a set of columns within an iView in the SAP MSS Business package. The customer can configure the group of columns that is displayed in a particular view by configuring the Object and Data Provider (OADP) tool within the SAP system.


http://help.sap.com/saphelp_46c/helpdata/en/74/df293581dc1f79e10000009b38f889/frameset.htm

http://help.sap.com/saphelp_46c/helpdata/en/48/35d4ad4abf11d18a0f0000e816ae6e/frameset.htm


In the SAP HR-OCI, the system uses the existing OADP functionality to extract the data from Organizational Management and represent the information as the contents of a column.



Input parameters The remote-enabled function module HCM_GET_ORGSTRUCTURE_AS_XML has the following input values: Field Data type Required Default value Meaning I_VIEWID CHAR(6) Yes – The view of an Organizational

Structure. Within the Business Package for Manager Self Service, a view is associated with a grouping of Organization Management data that can be represented as one or more columns of hierarchical information.

I_ORGSCENARIO CHAR(4) No – Query Scenario from table T77SCENQY. Used to specify, via an SAP Query, the additional data or attributes of the Organizational Management objects that are to be extracted from the SAP system.

I_OTYPE CHAR(2) No US Object type; the default value 'US' corresponds to the 'user' object. This field is used to determine the objects that are associated with the request.

I_OBJID CHAR(45) No SY-UNAME Extended object ID; the default value corresponds to the SAP user name. Used in conjunction with the View ID and the object type, the object ID will direct the system to which Organizational Management objects will be extracted by the function module.

I_PLANVARIANT CHAR(2) No – Plan Version I_BEGINDATE DATS(8) No SY-DATUM Specifies the beginning of the

date range from which to extract the Organizational Management data.

I_ENDDATE DATS(8) No SY-DATUM Specifies the end of the date range from which to extract the Organizational Management data.

I_KEYDATE DATS(8) No SY-DATUM Key date; specifies the date on which the additional information on the Organizational Management object is to be extracted.



Below is a detailed description of the input parameters of the function module. Note: The launching parameters can be used to populate some of these fields. I_VIEWID: In the back-end SAP system, the customer can use the OADP tool to configure an Organizational Management view. The view or View ID controls several different aspects of the information returned from the Interface. These aspects are:

Root path: The root path determines the root (or top-level) Organizational Management Object(s) based on the object type (ref. I_OTYPE) and object ID (ref. I_OBJID). Often, a root object is an organizational unit in which a manager holds the chief position.

The root path can be configured in the OADP view customization in one of two ways.

o It can be set using the standard evaluation path functionality in the SAP Organizational Management system.

o Alternatively, a customer SAP function module can be used to determine the root objects.

Evaluation path: The evaluation path determines the Organizational Objects that are

subordinate to the root objects. It specifies the particular type or types of objects that are returned in the function module. For example, an evaluation path could be used to return data on the people who hold positions that are a part of a root organizational unit.

Like the root path, the evaluation path can be set using standard SAP Organizational Management configuration or through the use of a custom function module.

Depth: The depth is specified within the View ID configuration. The depth is a number that specifies the number of organizational levels that should be displayed within the view.

Column group: The OADP tool can be used to extract additional data on the objects in a

particular view. The additional data can be represented as the contents of a column of information, where each column stores a specific piece of information. For example, a column can be an employee's entry date to the enterprise (if the object is a person), or a master cost center assigned to an organization unit (if the object is an organization unit). The columns are determined via the standard OADP configuration.

A column group is a collection of columns of data that can be associated with the view. This allows one or more columns of additional information that can be associated with a view. This information can be exported back through the output of the function module.

The View ID can be obtained from the launching parameter if the launching iView scenario is used. Otherwise, if the launching link is used, the View ID must be determined by the calling application in another fashion. I_ORGSCENARIO: As noted above, additional information about the objects extracted from Organizational Management can be determined from the grouping of columns that are associated with the View ID. In addition to this, additional data about the objects can be extracted through the use of SAP Queries. A query scenario a set of SAP Queries that can be used to pull information about the objects that are not associated with the specific column grouping defined in the view.



The configuration of the query scenarios is part of the customer's SAP system configuration. Like the View ID, the query scenario can be accessed from the launching parameters if the launching iView scenario is selected. I_OTYPE: The object type specifies the type of object that is being referenced by the object ID (I_OBJID). For example, the default value 'US' refers to an SAP system user. I_OBJID: The object ID is a unique identifier for an object with which the desired Organizational Management objects and structure are associated. For example, if the object ID is a user name (and object type is 'US'), then the function module extracts the Organization Management objects associated to the user that are determined from the View ID. I_PLANVARIANT: The plan version can be used to specify different plans within your Organizational Management structure. This allows multiple Organizational Management plans to be managed in parallel. I_BEGINDATE, I_ENDDATE: These date fields are used to specify the period of time over which the relevant Organizational Management objects are to be extracted. The begin date must be prior to the end date. If no begin date is specified, the SAP system date is used. If no end date is specified, the system date is used. I_KEYDATE: The key date, which must lie between the begin date and the end date (inclusive), specifies the date on which the additional data of the Organizational Management objects is to be extracted. As with the begin and end dates, the key date is the system date if no date is specified.



Output file The Remote Function Call (RFC) returns the following results: Field Data type Meaning XMLSTRING XSTRING

(XML) XML structure in UTF-8 conforming to the SAP XML Schema for Organizational Charting

RETURN BAPIRETURN Structured field for returning information about an error that occurred in the remote function call

The structure of the XML file is outlined in more detail below. The BAPIRETURN data type is a structured field with the following structure: Field Data type Meaning TYPE CHAR(1) The message type. The message types are:

S: Success E: Error W: Warning I: Informational A: Abort

In the HR OCI v1.0, only the 'E' message type is used. ID CHAR(20) The message class. NUMBER CHAR(3) The message number. MESSAGE CHAR(220) The text of the message. LOG_NO CHAR(20) The log number in the application log. LOG_MSG_NO NUMC(6) The internal message serial number in the application log. MESSAGE_V1 CHAR(50) MESSAGE_V2 CHAR(50) MESSAGE_V3 CHAR(50) MESSAGE_V4 CHAR(50)

Message variables. The message variables will be used in the creation of the MESSAGE field

If a problem occurs within the interface, an error message will be returned in the RETURN field. The function module HCM_GET_ORGSTRUCTURE_AS_XML uses the input data to perform the following three steps:

1. Extracting the relevant objects and hierarchical structures from SAP Organizational Management;

2. Collecting the data from the extracted objects and structures from SAP Organizational Management and SAP Personnel Administration;

3. Transforming the objects and data in the XML files conforming to the SAP XML schema for Organizational Charting.



SAP XML Schema for Organizational Charting As noted in the previous section, the function module HCM_GET_ORGSTRUCTURE_AS_XML returns the organizational data as an XML file. This file conforms to the SAP XML Schema for Organization Charting. The SAP XML Schema for Organizational Charting is the following: <?xml version="1.0" encoding="UTF-8" ?> <xsd:schema xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="OrganizationalStructureQueryResponse" type="OrganizationalStructureQueryResponse"/> <xsd:complexType name="OrganizationalStructureQueryResponse"> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="unbounded" name="OrganizationalEntity" type="OrganizationalEntity"/> <xsd:element minOccurs="0" maxOccurs="unbounded" name="KeyDescription" type="KeyDescription"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="OrganizationalEntity"> <xsd:sequence> <xsd:group ref="DefaultSet"/> <xsd:element minOccurs="0" maxOccurs="unbounded" name="Child" type="Child"/> <xsd:element minOccurs="0" maxOccurs="unbounded" name="AdditionalData" type="AdditionalData"/> </xsd:sequence> </xsd:complexType> <xsd:group name="DefaultSet"> <xsd:sequence> <xsd:element name="Type" type="xsd:token"/> <xsd:element name="ID" type="xsd:token"/> <xsd:element name="Relation" type="xsd:token"/> <xsd:element name="RelationBeginDate" type="xsd:date"/> <xsd:element name="RelationEndDate" type="xsd:date"/> <xsd:element minOccurs="0" maxOccurs="1" name="Name" type="xsd:token"/> <xsd:element minOccurs="0" maxOccurs="1" name="BeginDate" type="xsd:date"/> <xsd:element minOccurs="0" maxOccurs="1" name="EndDate" type="xsd:date"/> </xsd:sequence> </xsd:group> <xsd:complexType name="Child"> <xsd:sequence> <xsd:group ref="DefaultSet"/> <xsd:element minOccurs="0" maxOccurs="unbounded" name="Child" type="Child"/> <xsd:element minOccurs="0" maxOccurs="unbounded" name="AdditionalData" type="AdditionalData"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="AdditionalData"> <xsd:sequence> <xsd:element name="Key" type="xsd:token"/> <xsd:element name="Value" type="xsd:token"/> </xsd:sequence>



</xsd:complexType> <xsd:complexType name="KeyDescription"> <xsd:sequence> <xsd:element name="Key" type="xsd:token"/> <xsd:element name="Description" type="xsd:token"/> </xsd:sequence> </xsd:complexType> </xsd:schema>

The element <OrganizationalStructureQueryResponse> The root element of the returned XML file is the <OrganizationalStructureQueryResponse>. The element <OrganizationalStructureQueryResponse> consists of one or more sequences of two elements of complex type:

A root organizational unit (<Organizational Entity>);

A link between a technical key and a description of the data extracted from SAP Organizational Management (<KeyDescription>).

Both of these elements are discussed in detail below.

The complex element <OrganizationalEntity> The complex type element <OrganizationalEntity> is a reference to a root organizational object, such as an organizational unit, a position, or a person. In this context, it refers to an organizational object that does not have any superior or parent organizational object, but may contain subordinate or child organizational objects that may have similar characteristics. It consists of a sequence of three elements, the group <DefaultSet>, and the two elements < Child> and < AdditionalData >, which are used to define the organizational unit as well all its subordinate components.

The element <KeyDescription> The <KeyDescription> element provides a link between a technical key value and its semantic meaning. It consists of a sequence of two elements, <Key> and <Description>. Both of these elements are normalized strings. The <Key> will usually refer to a technical value from the SAP system. The associated <Description> element is used to describe the semantics of the <Key> element. For example, in the SAP system, a technical field containing the date of birth from an employee's master data is P0002-GBDAT. A <KeyDescription> element that could be used to describe the relationship between the technical field P0002-GBDAT and its meaning could look like this:

… <

…

Version 1.0, Sep

<KeyDescription> <Key>P0002-GBDAT</Key> <Description>Date of Birth</Description> </KeyDescription>

tember 2005 21


The group <DefaultSet> The group <DefaultSet> consists of seven elements, each of a simple type. It is in this group that the relational information of the Organizational Management object is contained. The seven elements are as follows: Element name Type Meaning Type token Object type. The type can be an organizational unit, a person, a

position, a job, etc. The value of this field is a two character normalized string and comes from an SAP table (T778O).

ID int Object ID within SAP Organizational Management. This is field is an eight-digit integer.

Relation token Nature of relationship with parent object. The relationship may take on values such as 'holder of' (as in the holder of a position), 'is a line supervisor of', etc. The value of this field is a four character normalized string. The association between the four character string and its meaning comes from an SAP table (T778V).

RelationBeginDate date The beginning date of the current relationship. RelationEndDate date The ending date of the current relationship. Name token The name of the object. BeginDate date The beginning date of the object within the Organizational

Management. This field is optional. EndDate date The ending date of the object within Organizational Management.

This field is optional. As a part of the <OrganizationalEntity> element, the object type can be any object within Organizational Management, such as (typically) an organizational unit, a person, or a position. We use the relationship value ‘A$$$’ to denote a parent object. The group <DefaultSet> is also used by the element <Child>, which is discussed in detail below. When this group is an element of a <Child> element, then the object type can also be of any Organization Management type.

The element <Child> The <Child> element is used to define subordinate objects to the root object <OrganizationalEntity>. These subordinate objects may be Organizational Management objects such as positions or other organizational units. It is also used to define objects that are subordinate to other <Child> objects. For example, a position object may have a person who holds the position as a child object, or an organizational unit may have a subordinate organizational unit as a child object. The <Child> element has the same element structure as <OrganizationalEntity>; namely the group <DefaultSet> and the complex elements < Child> and < AdditionalData >. The sub elements are used in the same was as in the <OrganizationalEntity> element. Thus, the difference between the <Child> and <OrganizationalEntity> lies in whether the object has a parent object or not. Example: Company ABC has two divisions, Division MNO and Division PQR. Therefore, an XML data stream that represents this organizational structure could look like the following:



<OrganizationalStructureQueryResponse> <OrganizationalEntity>

<Type>O</Type> <ID>10000000</ID> <Relation>A$$$</Relation> <RelationBeginDate>2003-01-01</RelationBeginDate> <RelationEndDate>9999-12-31<RelationEndDate> <Name>ABC</Name> <Child> <Type>O</Type> <ID>11000000</ID> <Relation>B002</Relation> <RelationBeginDate>2003-01-01</RelationBeginDate> <RelationEndDate>9999-12-31<RelationEndDate> <Name>MNO</Name> <AdditionalData> <Key>ORG_NAME</Key> <Value>Division MNO</Value> </AdditionalData> <AdditionalData> <Key>HQLOC</Key> <Value>Vancouver, BC, Canada</Value> </AdditionalData> </Child> <Child> <Type>O</Type> <ID>120000000</ID> <Relation>B002</Relation> <RelationBeginDate>2003-01-01</RelationBeginDate> <RelationEndDate>9999-12-31<RelationEndDate> <Name>PQR</Name> <AdditionalData> <Key>ORG_NAME</Key> <Value>Division PQR</Value> </AdditionalData> <AdditionalData> <Key>HQLOC</Key> <Value>Latrobe, PA, USA</Value> </AdditionalData> </Child> <AdditionalData> <Key>ORG_NAME</Key> <Value>Company ABC</Value> </AdditionalData> <AdditionalData> <Key>HQLOC</Key> <Value>Palo Alto, CA, USA</Value> </AdditionalData> </OrganizationalEntity> <KeyDescription> <Key>ORG_NAME</Key> <Description>Name of organizational unit</Description> </KeyDescription> <KeyDescription> <Key>HQLOC</Key>



Note: Type 'O' designates an organizational unit. The relation 'B002' means 'is a line supervisor of'.

The element <AdditionalData> The element <AdditionalData> is of complex type and consists of a sequence of two elements, <Key> and <Value>. The <AdditionalData> element contains additional attributes about the object that is referenced in <DefaultSet>. For example, if the object referenced in <DefaultSet> is a person, then the <AdditionalData> element can store attributes associated with the person, such as the person's name, telephone number, or other personnel administrative data. In the element <AdditionalData>, <Key> corresponds with the technical key that is referenced in <KeyDescription>, and the <Value> element is the value for the description associated with the <Key> element. Example: In the SAP system, a technical field containing the employee's name in master data is ORG_STEXT_JS. If the name is included in the data queried from the SAP Organization Management system, there may be a <KeyDescription> element that looks like the following:

…

<KeyDescription> <Key>ORG_STEXT_JS </Key> <Description>Name</Description> </KeyDescription>

If the object referenced in <DefaultSet> is a person (as part of a <Child> element), then that person's name may be stored in an <AdditionalData> reference with the technical key ORG_STEXT_JS. For example, if the employee's name is Joe Smith, then the <AdditionalData> element may look like:

…

<AdditionalData> <Key>ORG_STEXT_JS </Key> <Value>Joe Smith</Value> </AdditionalData>

In other words, the <KeyDescription> element gives the semantic definition of the information that is stored in the <AdditionalData> element through the linking of the technical name <Key>. It is possible that an object (identified by a unique combination of object type and object ID) may appear more than one time in the XML files if multiple relationships exist; for example, a position that is the head of an organizational unit is also a position within that organizational unit. If a customer configures the OCI to retrieve both relationships, the position will appear twice in the XML file, once with the relationship that describes it as the head of the organizational unit (B012) and again for the relationship as a position within the organization unit (B003).


Documents

SAP HR Organizational Charting Interface€¦ · display the hierarchical data in a graphic presentation. The interface utilizes the functionality provided by the Object and Data