SAP NetWeaverHow-To Guide

How to Create a New Event foreSocial

Applicable Releases:

SAP_HR 6.00 and higher

Version 1.0

October 2013

i

© Copyright 2012 SAP AG or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the expresspermission of SAP AG. The information contained herein may be changed without prior notice.Some software products marketed by SAP AG and its distributors contain proprietary software components of othersoftware vendors.National product specifications may vary.These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only,without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect tothe materials. The only warranties for SAP Group products and services are those that are set forth in the express warrantystatements accompanying such products and services, if any. Nothing herein should be construed as constituting anadditional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registeredtrademarks of SAP AG in Germany and other countries. Please see http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices.

SAP NetWeaver “How-to” Guides are intended to simplify the product implementation. While specific product features andprocedures typically are explained in a practical business context, it is not implied that those features and procedures arethe only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additionalinformation, clarification or support, please refer to SAP Consulting.Any software coding and/or code lines / strings (“Code”) included in this documentation are only examples and are notintended to be used in a productive system environment. The Code is only intended better explain and visualize the syntaxand phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, andSAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAPintentionally or grossly negligent.

Disclaimer:Some components of this product are based on Java™. Any code change in these components may cause unpredictable andsevere malfunctions and is therefore expressively prohibited, as is any decompilation of these components.Any Java™ Source Code delivered with this product is only to be used by SAP’s Support Services and may not be modifiedor altered in any way.

ii

Document History

Document Version Description

1.0 Initial version

iii

Typographic Conventions

Type Style Description

Example Text Words or characters quotedfrom the screen. Theseinclude field names, screentitles, pushbuttons labels,menu names, menu paths,and menu options.Cross-references to otherdocumentation

Example text Emphasized words orphrases in body text, graphictitles, and table titles

Example text File and directory names andtheir paths, messages,names of variables andparameters, source text, andnames of installation,upgrade and database tools.

Example text User entry texts. These arewords or characters that youenter in the system exactly asthey appear in thedocumentation.

<Exampletext>

Variable user entry. Anglebrackets indicate that youreplace these words andcharacters with appropriateentries to make entries in thesystem.

EXAMPLE TEXT Keys on the keyboard, forexample, F2 or ENTER.

Icons

Icon Description

Caution

Important

Note

Recommendation or Tip

Example

iv

Table of Contents1. Business Background .....................................................................................................1

2. Technical Background ....................................................................................................1

3. How to Create a New Event for eSocial ..........................................................................53.1 Create the processing class of the event ...................................................................53.2 Customize the eSocial information type table ............................................................53.3 Define the eSocial application tables .........................................................................53.4 Create a data structure .............................................................................................63.5 Implement the processing class ................................................................................73.6 Customize the eSocial event type table .....................................................................8

4. Appendix ........................................................................................................................ 104.1 Appendix A – Objects reference .............................................................................. 104.2 Appendix B – Example of processing class implementation ..................................... 104.3 Appendix C – Example of logging errors.................................................................. 144.4 Appendix D – When a new version of the class is necessary ................................... 144.5 Appendix E – HCM Objects ..................................................................................... 14

1. Business Background

eSocial is a system for digital bookkeeping of payroll, and of work, tax and social insurance tributes,valid for all employment contracts established in Brazil. Employers must send information about allemployees to the relevant government authorities in a specific timeframe. The information sent to thegovernment is grouped in events, such as hiring, firing or leave notice.

2. Technical Background

The eSocial framework manages the process of extracting the data, storing the data and generatingthe XML files to be sent to the government.

The logic to get the data from the data base is managed by specific business logic classes.

The eSocial framework executes the processing of each event and manages the data returned by theevent processing. The processing of the event is business dependent; therefore each event needs tohave a specific class extracting the data from database.

Following is designed the components of the eSocial framework.

Main framework components:

eSocial Data processing Engine: main component of the framework that is in charge of thefull processing. It is the entry point to use the framework, in other words, you use this classwhen you want to run the eSocial.

eSocial Data Management: it is in charge of storing and reading data from database.

eSocial Data Extraction Business Logic: it is the specific logic of the events to extract datafrom database and generate the events.

eSocial Change Manager: it is in charge of controlling the generation of the eventsrespecting rectification/exclusion/changing rules of the eSocial. It deals with what weregenerated by the business logic and controls what should and what should not be sent toGovernment. It also stores a log of the employee master data changes to be able to run theright eSocial events.

Framework knowledge prerequisites:

Processing class of the event is the class that contains the business logic to fill the event data.This class is triggered by the framework according to customizing. It receives the selectionobject as parameter and, according to this selection; the class has to generate one or moreinstances of the CL_HRPAYBR_EFDF_EVENT class.

The customizing of the event types and the corresponding processing classes are stored in thetable T7BREFD_EVTYPE.

The framework controls the events by the table T7BREFD_EVENT. For each event generated inproductive mode an entry is created in this table and an ID is generated (EVENT_ID) to identifythe event. The main fields of the table are:

Event ID: unique global ID of the eventEvent type: event type, link to table T7BREFD_EVTYPE

Status: current status of the eventInformation type and value: fields to inform what the content of the event refers to, e.g.employees, branches, companiesBegin and end dates: valid dates of the event

When the eSocial events are generated, they have to be stored in application data tables toallow you to send the XML file in a future time. The application tables you created must have allfields necessary by the event XML file. You can create one or more tables, and each event canhave one or more entries in each table you created.

You can reuse tables that had been created or create new tables in case the existing ones donot have all the information you need. In case more than one table is needed to store the eventdata in the database, you have to create a data dictionary structure which can contain a deepstructure with the table lines needed. If the event data uses just one application table, the datastructure of the event can be the line of the table.

The processing class fills the table fields and returns them to the framework so that theframework saves them in the database.

The following ABAP OO interfaces are available for eSocial:IF_HRPAYBR_EFDF_DATA_EXTRACTOR: interface to be implemented by businessclasses to extract data from the database.IF_HRPAYBR_EFDF_DATA_TRANS: interface to be implemented by business classesto send the events via Web Services using a technology such as Proxies and PI.IF_HRPAYBR_EFDF_TYPINF_CONV: interface to be implemented by business classesto define how the information type (employee number, employer, wage type etc.) mustbe displayed.

Selection class is a class that is in charge of carrying the selection data from the selectionscreen of the application that triggers the framework to the processing class of the event. It hasthree classes for selection:

CL_HRPAYBR_EFDF_SELECTION: this class contains basic data, like the start and endselection, whether the execution is productive or not, whether the application needs adetailed log, and extra parameters if necessary. This class should be used for genericselection of events.CL_HRPAYBR_EFDF_EE_SELECTION: this is a subclass of theCL_HRPAYBR_EFDF_SELECTION class. It adds the capacity to hold employeeinformation (personal number). This class should be used for employee-based events.CL_HRPAYBR_EFDF_ER_SELECTION: this is a subclass theCL_HRPAYBR_EFDF_SELECTION class. It adds the capacity to hold companyinformation (BUKRS). This class should be used for employer-based events.

The flow of the eSocial execution is the following:

3. How to Create a New Event for eSocial

Below is an overview of how to create a new event for eSocial:

1. Create the processing class of the event2. Customize the eSocial information type table3. Define the eSocial application tables4. Create a data structure5. Implement the processing class6. Customize the eSocial event type table

The following sections explain each of those steps in detail.

3.1 Create the processing class of the event...

1. In transaction SE24, create the processing class that implements interfaceIF_HRPAYBR_EFDF_DATA_EXTRATOR. Create the class as a public class. Note that thenaming convention for SAP is CL_HRPAYBR_EFDE_<free_name>, and that there is nonaming convention for customer classes.

a

3.2 Customize the eSocial information type table...

The information type table stores the main type of information that the event contains; for example,employee, wage type, company.

1. In Customizing for Payroll, choose Payroll: Brazil -> eSocial -> Basic settings -> Set informationtypes.

2. Fill the following fields:a. Information type – define a code for the information type. Note that the namespaces are

the following: From 01 to 79: SAP namespace From 80 to 99: customer namespace

b. Conversion class – enter an optional class that can be used for converting theinformation type to be displayed in the screen. This class has to implement theIF_HRPAYBR_EFDF_TYPINF_CONV interface.

3.3 Define the eSocial application tables...

1. Identify which eSocial application tables are necessary to cover the event data.2. If necessary, create new tables following the instructions below. Note that the naming

convention for SAP: T7BREFD_<free name>, and that there is not naming convention forcustomer tables.

Enter the HRPADBR_EFD_S_APP_KEY_FIELDS structure at the beginning of the table as.INCLUDE and set as key of the table.

Enter the HRPADBR_EFD_S_APP_OTHER_FIELDS structure as .INCLUDE after theHRPADBR_EFD_S_APP_KEY_FIELDS include.

Enter delivery class A. The fields of the structures above are filled by the framework. The other fields of the table

have to be filled by the processing class.

3.4 Create a data structure...

Design a data structure to contain all the fields necessary in the XML and create the data structure inthe data dictionary.

When designing a data structure, take the rules below into consideration: Two kinds of structures must exist:

o Flat structure: structure that only contains data elements as fields. Flat structuresMUST be lines of eSocial data tables.

o Deep structure: structure that only contains structures and table types as fields. A parent of an application table is the application table that is on the previous level,

according to the image below:

(*) eSocial application tables

The structure can be either a line of an eSocial table (see section 3.3), or have a deep structure witheSocial table lines inside of it.

Example:HRPAYBR_EFD_S_PAY_EVENT EMPLOYEE T7BREFD_EE PAYROLLS HRPAYBR_EFD_T_PAYROLLS

PAYROLL HRPAYBR_EFD_S_PAYROLL PAY_DATA T7BREFD_PAYROLL WAGETYPES HRPAYBR_EFD_T_WAGETYPES LINE T7BREFD_WTS

In this example, the event consists of employee data, each employee can have several payroll runs,and each payroll run can have several wage types. Each line in the example corresponds to thefollowing:

The data structure HRPAYBR_EFD_S_PAY_EVENT is the main structure and it has two fields:EMPLOYEE and PAYROLLS.

The EMPLOYEE field is the line of the table which stores employee information.

Main Structure

Parent A*

Deep structure

Child of A*

Child of A*

Child of A andParent B*

Deep structure Child of B*

The PAYROLLS field is a table type of HRPAYBR_EFD_S_PAYROLL that is used for organizingthe data. This structure has two fields: PAY_DATA and WAGETYPES.

The PAY_DATA field is the payroll data to be saved in the database. The WAGETYPES field is a table type of the table which saves the wage type information for the

event.In this example, LINE (wage type) is a child structure of the PAY_DATA (payroll) structure, andPAY_DATA is a child structure of the EMPLOYEE structure.

For table events1 use the T7BREFD_DTCTRL application table to control the dates of the event, thanthe framework will be able to handle the insertion/change/deletion process of this event types. Thistable contains the following fields:

Begin date (BEGDA): represents the begin date of the event.End date (ENDDA): represents the end date of the event.Previous begin date (PREV_BEGDA): represents the begin date of the event which wasalready sent to the Government. It will be filled by the framework automatically in case of achange operationPrevious end date (PREV_ENDDA): represents the end date of the event which was alreadysent to the Government. It will be filled by the framework automatically in case of a changeoperation

3.5 Implement the processing class...

1. Implement the processing class that you created in step 3.1. For examples of implementation,see the appendix A. If necessary, create a constructor method for the class, but withoutparameters.

Method CREATE_STRUCTURE

o Return a reference to the data structure that contains all the fields of the event.o The statement CREATE DATA must be used.

Method PROCESS

o Extract the data from the database and create instances of the classCL_HRPAYBR_EFDF_EVENT to encapsulate each event.

o The method has to use the selection object IO_SELECTION passed by parameter tofilter the data.

The selection object is filled by the application that executes the eSocialframework.

To process employee events, use the HCM Objects framework to reademployee information (see appendix D).

The selection object can also contain other parameters that are set in theapplication

o The CONSTRUCTOR method of the class CL_HRPAYBR_EFDF_EVENT is called with thefollowing parameters:

Event type – the same code defined on step 3.6 (see below).

1 Table events are defined by the Government as the events of eSocial which reports data related totables, like wage type table, branch table, etc.

Information value – the main information that the event contains; forexample, personal number, CPF document, branch, company, according toinformation type returned by the method GET_INFORMATION_TYPE. Forstandard values use a constant of the IF_HRPAYBR_EFD_CONSTANTS_Cinterface.Event dates (BEGDA and ENDDA) – the dates that the event refers to. If theevent contains just one date, like hiring, the event dates (BEGDA and ENDDA)are the hiring date of the employee. If the event is a table event whichcontains start and end dates, these dates have to be used.Reference to data structure – the reference to the data structure thatcontains the data of the event, the same one defined on step 3.4.

The fields Event type, Information type, Information value and the eventdates (BEGDA and ENDDA) are the key of the event. They are used to identifythe event in case of rectification or cancelation of the events. The informationtype is returned by the GET_INFORMATION_TYPE method.

o Use the CREATE DATA statement and get its reference to set it in the event class. Donot use local definition of the structure like DATA or attribute of the class.

SAP recommends calling the CREATE_STRUCTURE method.o A best practice is to create another method inside the class to fill the fields of the

structure and not do this processing in the PROCESS method.o Let inside the PROCESS method just the code to create the structure and the event

instance.o In the class there is no need to deal with rectification process because it will be done

by the framework. Just generate the events according to your database and theframework will control the deletion, insertion and rectification process.

Method GET_EVENTS

o Return a table with the reference to the events created in the method PROCESS

Method GET_INFORMATION_TYPE

o Need to return the type of information on which the event refers to, for example,employee, CPF, company.

o The returned value can to be one of the standards that are defined in the interfaceIF_HRPAYBR_EFD_CONSTANTS_C.

Log errors and warnings by using the instance of the CL_HRPAYBR_EFDF_EVENT class toappend exception and messages from message classes and define if the exception is an erroror warning.

To log general errors and warnings which are not specific from events, use the instance of theclass CL_HRPAYBR_EFDF_DATA_LOG which is passed as parameter to the method.

3.6 Customize the eSocial event type table...

The event type table is the table that stores the event types that can be executed by the framework. Itmainly identifies an event type as a numerical code, and it stores the name of the class that processesthe event (the class created in step 3.1).

1. In Customizing for Payroll, choose Payroll: Brazil -> eSocial -> Basic settings -> Set event types.2. Fill the following fields:

a. Event type – define a code for the event. Note that the namespaces are the following:

i. From 0001 to 7999: SAP namespaceii. From 8000 to 9999: customer namespace

b. Start and end datesc. Processing class – enter a class that you created in step 3.1.d. Classification – there are 3 possible values:

i. Payroll events: events which will contain payroll information, e.g. S-1200ii. Table events: events which will contain data related to company customizing, e.g.

S-1000, S-1010.iii. Worker events: events which will contain employee master data, e.g. S-2100, S-

2220.e. Visualization – there are 2 possible values:

i. Detailed: display the event data in the log in a detailed mode, respecting the tablewhich it is stored.

ii. Flat: display the all the event data in the log in a flat structure, it means,concatenates all the tables of the event in one single data structure.

f. Event legal code – legal code of the event, e.g. ‘S-1000’

4. Appendix

4.1 Appendix A – Objects reference

Object Description

T7BREFD_EEINFO Application table with employee information

HRPADBR_EFDE_S_EMPLOYER_INFO Data structure of table event

HRPADBR_EFDE_S_INITIAL_REG Data structure of employee event

CL_HRPAYBR_EFDE_EMPLOYER Processing class of table event

CL_HRPAYBR_EFDE_INITIAL_REG Processing class of employee event

4.2 Appendix B – Example of processing classimplementation

Method CREATE_STRUCTURE

METHOD if_hrpaybr_efdf_data_extractor~create_structure.

CREATE DATA rr_data TYPE <data_structure>.ENDMETHOD.

Method GET_EVENTS

METHOD if_hrpaybr_efdf_data_extractor~get_events.

et_events = mt_events.

ENDMETHOD.

Method GET_INFORMATION_TYPE

METHOD if_hrpaybr_efdf_data_extractor~get_information_type.

rv_type = IF_HRPAYBR_EFD_CONSTANTS_C=> GC_INFORMATION_TYPE_EMPLOYEE.ENDMETHOD.

Method PROCESSExample of implementation using default selectionMETHOD if_hrpaybr_efdf_data_extractor~process.

DATA lr_data TYPE REF TO <structure of the event>.DATA lo_event TYPE REF TO cl_hrpaybr_efdf_event.

lr_data ?= me->create_structure( ).

* Fill the fields according to business rule me->fill_fields( CHANGING cs_data = lr_data->* ).

* Create the event instanceCREATE OBJECT lo_eventEXPORTING

iv_begda = <date>

iv_endda = <date>

iv_inf_value = <inf_value>

iv_event_type = if_hrpaybr_efd_constants_c=>gc_event_type_employer“Constant ir_data = lr_data.

* Store the event in a instance tableAPPEND lo_event TO mt_events.

ENDMETHOD.

Example of implementation with employee selectionMETHOD if_hrpaybr_efdf_data_extractor~process.

DATA lv_pernr TYPE pernr_d.

DATA lt_pernr_table TYPE hrpay99_pernr_table.

DATA lr_data TYPE REF TO <structure of the event>.DATA lo_event TYPE REF TO cl_hrpaybr_efdf_event.DATA lo_ee_selection TYPE REF TO cl_hrpaybr_efdf_ee_selection.DATA lo_employee TYPE REF TO cl_hrpadbr_employee.

* Cast the selection to work with employees lo_ee_selection ?= io_selection.

lo_ee_selection->get_pernr_table(IMPORTING

et_pernr_table = lt_pernr_table ).

LOOP AT lt_pernr_table INTO lv_pernr.

lr_data ?= me->create_structure( ).

lo_employee = lo_ee_selection->create_employee_instance( ).

* Fill the fields according to business rule me->fill_fields( EXPORTING io_employee = lo_employee

CHANGINGcs_data = lr_data->* ).

* Create the event instanceCREATE OBJECT lo_eventEXPORTING

iv_begda = <date>

iv_endda = <date>

iv_event_type = if_hrpaybr_efd_constants_c=>gc_event_type_initial_reg

iv_inf_value = lv_pernr ir_data = lr_data.

* Store the event in a instance tableAPPEND lo_event TO mt_events.

ENDLOOP.

ENDMETHOD.

Example of implementation with employee selection grouping by CPF document

Define an internal table with CPF and EVENT as fields, like:

TYPES: BEGIN OF gty_s_cpf_event, cpf TYPE pbr_cpfnr, event TYPE REF TO cl_hrpaybr_efdf_event,

END OF gty_s_cpf_event.

Method source code

METHOD if_hrpaybr_efdf_data_extractor~process.

DATA lv_pernr TYPE pernr_d.

DATA lv_cpf TYPE pbr_cpfnr.

DATA ls_cpf_event TYPE gty_s_cpf_event.DATA lt_pernr_table TYPE hrpay99_pernr_table.

DATA lr_data TYPE REF TO <structure of the event>.DATA lo_event TYPE REF TO cl_hrpaybr_efdf_event.DATA lo_ee_selection TYPE REF TO cl_hrpaybr_efdf_ee_selection.DATA lo_employee TYPE REF TO cl_hrpadbr_employee.DATA lo_master_data TYPE REF TO cl_hrpadbr_master_data.

* Cast the selection to work with employees lo_ee_selection ?= io_selection.

lo_ee_selection->get_pernr_table(IMPORTING

et_pernr_table = lt_pernr_table ).

LOOP AT lt_pernr_table INTO lv_pernr.

lo_employee = lo_ee_selection->create_employee_instance( ).

lo_master_data = lo_employee->get_master_data( ).

lv_cpf = lo_master_data->get_cpf( ).

* Instance attribute table with CPF and EVENT as fieldsREAD TABLE mth_cpf_event INTO ls_cpf_event WITH KEY cpf = lv_cpf.

IF ( sy-subrc <> 0 ).

lr_data ?= me->create_structure( ).

* Create the event instanceCREATE OBJECT lo_eventEXPORTING

iv_begda = <date>

iv_endda = <date>

iv_event_type = if_hrpaybr_efd_constants_c=>gc_event_type_initial_reg

iv_inf_value = lv_cpf ir_data = lr_data.

ls_cpf_event-cpf = lv_cpf.

ls_cpf_event-event = lo_event.

* Store the event in a instance tableAPPEND ls_cpf_event TO mt_cpf_events.

ELSE.

lr_data = ls_cpf_event-event->get_date( ).

ENDIF.

* Fill the fields according to business rule me->fill_fields( EXPORTING io_employee = lo_employee

CHANGINGcs_data = lr_data->* ).

ENDLOOP.

ENDMETHOD.

4.3 Appendix C – Example of logging errors

1. Using the instance of the class CL_HRPAYBR_EFDF_EVENT.

CATCH cx_hrpadbr_infty_not_found INTO lx_exception. io_event->append_exception( EXPORTING io_exception = lx_exception iv_msgty = 'E' ).

2. General errors.

IF lv_ctps_nr IS INITIAL OR lv_ctps_serie IS INITIAL OR lv_ctps_uf IS INITIAL.

lv_msg_var2 = text-t03.

io_event->append_message(EXPORTING

iv_message_id = 'HRPAYBR_EFD' iv_message_type = 'E' iv_message_number = '001' iv_message_var1 = lc_record iv_message_var2 = lv_msg_var2 ).

RETURN.ENDIF.

4.4 Appendix D – When a new version of the class isnecessary

For future maintenance, it is necessary to create a new version of the processing class and delimit theV_T7BREFD_EVTYPE table view in following situations:

You have removed fields/structures/tables from the event structure You have changed the hierarchy of the event structure You have changed the structure of event You have changed the information type of the event You have changed the selection class that the processing class is expecting, for example fromCL_HRPAYBR_EFDF_EE_SELECTION to CL_HRPAYBR_EFDF_SELECTION

4.5 Appendix E – HCM Objects

For a faster approach on developing events that have employee information, SAP recommends theuse of the HCM Objects framework.

The HCM Objects framework has been developed to retrieve employee master data (infotype data)more easily. This framework also reads customizing data that are related to the infotypes.

In case the HCM Objects framework does not have the information that you need for eSocial, SAPrecommends that you consider whether the information necessary is applicable to be inserted in theframework. If so, enhance the HCM Objects framework; otherwise implement it on your processingclass.

Insert the following information in the HCM Objects framework: New infotypes Retrieval of information related to infotype entries Reading of customizing tables which depend on an infotype entry, like absence mapping

Do not insert the following information in the HCM Objects framework: Conversion of data to report format

Example of codeDATA lo_employee TYPE REF TO cl_hrpadbr_employee.DATA lo_org_assign TYPE REF TO cl_hrpadbr_org_assign.DATA ls_t001p TYPE REF TO t001p.

…

* Create the employee instanceCREATE OBJECT lo_employeeEXPORTING

Iv_pernr = lv_pernr.

* The the infotype 0001 – Casting the object returnedlo_org_assign ?= lo_employee->get_last( iv_infty = ‘0001’

iv_begda = lv_begda iv_endda = lv_endda ).

* Read the entry of T001P which have information about the subareals_t001p = lo_org_assign->get_hr_subarea( ).

ls_output_data-bukrs = lo_org_assign->ms_org_assign-bukrs.

ls_output_data-moabw = ls_t001p-moabw.

…