You are on page 1of 20

SAP NetWeaver

How-To Guide

How to Create a New Event for


eSocial

Applicable Releases:
SAP_HR 6.00 and higher

Version 1.0
October 2013

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 express
permission 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 other
software 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 to
the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty
statements accompanying such products and services, if any. Nothing herein should be construed as constituting an
additional warranty.
SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered
trademarks of SAP AG in Germany and other countries.
Please see http://www.sap.com/corporateen/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 and
procedures typically are explained in a practical business context, it is not implied that those features and procedures are
the only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additional
information, 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 not
intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax
and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and
SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP
intentionally or grossly negligent.
Disclaimer:
Some components of this product are based on Java. Any code change in these components may cause unpredictable and
severe 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 SAPs Support Services and may not be modified
or altered in any way.

Document History
Document Version

Description

1.0

Initial version

ii

Typographic Conventions
Type Style

Description

Example Text

Words or characters quoted


from the screen. These
include field names, screen
titles, pushbuttons labels,
menu names, menu paths,
and menu options.
Cross-references to other
documentation

Example text

Emphasized words or
phrases in body text, graphic
titles, and table titles

Example text

File and directory names and


their paths, messages,
names of variables and
parameters, source text, and
names of installation,
upgrade and database tools.

Example text

User entry texts. These are


words or characters that you
enter in the system exactly as
they appear in the
documentation.

<Example
text>

Variable user entry. Angle


brackets indicate that you
replace these words and
characters with appropriate
entries to make entries in the
system.

EXAMPLE TEXT

Keys on the keyboard, for


example, F2 or ENTER.

Icons
Icon

Description
Caution
Important
Note
Recommendation or Tip
Example

iii

Table of Contents
1.

Business Background .....................................................................................................1

2.

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

3.

How to Create a New Event for eSocial ..........................................................................5


3.1 Create the processing class of the event ...................................................................5
3.2 Customize the eSocial information type table ............................................................5
3.3 Define the eSocial application tables .........................................................................5
3.4 Create a data structure .............................................................................................6
3.5 Implement the processing class ................................................................................7
3.6 Customize the eSocial event type table .....................................................................8

4.

Appendix........................................................................................................................ 10
4.1 Appendix A Objects reference .............................................................................. 10
4.2 Appendix B Example of processing class implementation ..................................... 10
4.3 Appendix C Example of logging errors.................................................................. 14
4.4 Appendix D When a new version of the class is necessary ................................... 14
4.5 Appendix E HCM Objects..................................................................................... 14

iv

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 all
employees to the relevant government authorities in a specific timeframe. The information sent to the
government 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 generating
the 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 the
event processing. The processing of the event is business dependent; therefore each event needs to
have 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 the
full processing. It is the entry point to use the framework, in other words, you use this class
when 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 data
from database and generate the events.
eSocial Change Manager: it is in charge of controlling the generation of the events
respecting rectification/exclusion/changing rules of the eSocial. It deals with what were
generated by the business logic and controls what should and what should not be sent to
Government. It also stores a log of the employee master data changes to be able to run the
right 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 selection
object as parameter and, according to this selection; the class has to generate one or more
instances of the CL_HRPAYBR_EFDF_EVENT class.
The customizing of the event types and the corresponding processing classes are stored in the
table T7BREFD_EVTYPE.
The framework controls the events by the table T7BREFD_EVENT. For each event generated in
productive mode an entry is created in this table and an ID is generated (EVENT_ID) to identify
the event. The main fields of the table are:
Event ID: unique global ID of the event
Event type: event type, link to table T7BREFD_EVTYPE
Status: current status of the event
Information type and value: fields to inform what the content of the event refers to, e.g.
employees, branches, companies
Begin and end dates: valid dates of the event
When the eSocial events are generated, they have to be stored in application data tables to
allow you to send the XML file in a future time. The application tables you created must have all
fields necessary by the event XML file. You can create one or more tables, and each event can
have 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 do
not have all the information you need. In case more than one table is needed to store the event
data in the database, you have to create a data dictionary structure which can contain a deep
structure with the table lines needed. If the event data uses just one application table, the data
structure 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 the
framework saves them in the database.
The following ABAP OO interfaces are available for eSocial:
IF_HRPAYBR_EFDF_DATA_EXTRACTOR: interface to be implemented by business
classes to extract data from the database.
IF_HRPAYBR_EFDF_DATA_TRANS: interface to be implemented by business classes
to 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 classes
to define how the information type (employee number, employer, wage type etc.) must
be displayed.

Selection class is a class that is in charge of carrying the selection data from the selection
screen of the application that triggers the framework to the processing class of the event. It has
three classes for selection:
CL_HRPAYBR_EFDF_SELECTION: this class contains basic data, like the start and end
selection, whether the execution is productive or not, whether the application needs a
detailed log, and extra parameters if necessary. This class should be used for generic
selection of events.
CL_HRPAYBR_EFDF_EE_SELECTION: this is a subclass of the
CL_HRPAYBR_EFDF_SELECTION class. It adds the capacity to hold employee
information (personal number). This class should be used for employee-based events.
CL_HRPAYBR_EFDF_ER_SELECTION: this is a subclass the
CL_HRPAYBR_EFDF_SELECTION class. It adds the capacity to hold company
information (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.
2.
3.
4.
5.
6.

Create the processing class of the event


Customize the eSocial information type table
Define the eSocial application tables
Create a data structure
Implement the processing class
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 interface


IF_HRPAYBR_EFDF_DATA_EXTRATOR. Create the class as a public class. Note that the
naming convention for SAP is CL_HRPAYBR_EFDE_<free_name>, and that there is no
naming 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 information
types.
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 the
information type to be displayed in the screen. This class has to implement the
IF_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 for
customer 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 the


HRPADBR_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 in
the 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 structures
MUST 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:
Child of A*
Parent A*
Main Structure

Child of A*
Deep structure
Child of A and
Parent B*
Deep structure

Child of B*

(*) eSocial application tables


The structure can be either a line of an eSocial table (see section 3.3), or have a deep structure with
eSocial table lines inside of it.
Example:
HRPAYBR_EFD_S_PAY_EVENT
EMPLOYEE
PAYROLLS
PAYROLL
PAY_DATA
WAGETYPES
LINE

T7BREFD_EE
HRPAYBR_EFD_T_PAYROLLS
HRPAYBR_EFD_S_PAYROLL
T7BREFD_PAYROLL
HRPAYBR_EFD_T_WAGETYPES
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 the
following:
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.

The PAYROLLS field is a table type of HRPAYBR_EFD_S_PAYROLL that is used for organizing
the 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, and
PAY_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, than
the framework will be able to handle the insertion/change/deletion process of this event types. This
table 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 was
already sent to the Government. It will be filled by the framework automatically in case of a
change operation
Previous end date (PREV_ENDDA): represents the end date of the event which was already
sent to the Government. It will be filled by the framework automatically in case of a change
operation

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 without
parameters.
Method CREATE_STRUCTURE
o
o

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

Method PROCESS
o

Extract the data from the database and create instances of the class
CL_HRPAYBR_EFDF_EVENT to encapsulate each event.

The method has to use the selection object IO_SELECTION passed by parameter to
filter the data.
The selection object is filled by the application that executes the eSocial
framework.
To process employee events, use the HCM Objects framework to read
employee information (see appendix D).
The selection object can also contain other parameters that are set in the
application
The CONSTRUCTOR method of the class CL_HRPAYBR_EFDF_EVENT is called with the
following parameters:
Event type the same code defined on step 3.6 (see below).

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

Information value the main information that the event contains; for
example, personal number, CPF document, branch, company, according to
information type returned by the method GET_INFORMATION_TYPE. For
standard values use a constant of the IF_HRPAYBR_EFD_CONSTANTS_C
interface.
Event dates (BEGDA and ENDDA) the dates that the event refers to. If the
event 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 which
contains start and end dates, these dates have to be used.
Reference to data structure the reference to the data structure that
contains the data of the event, the same one defined on step 3.4.
The fields Event type, Information type, Information value and the event
dates (BEGDA and ENDDA) are the key of the event. They are used to identify
the event in case of rectification or cancelation of the events. The information
type is returned by the GET_INFORMATION_TYPE method.
o

o
o
o

Use the CREATE DATA statement and get its reference to set it in the event class. Do
not use local definition of the structure like DATA or attribute of the class.
SAP recommends calling the CREATE_STRUCTURE method.
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.
Let inside the PROCESS method just the code to create the structure and the event
instance.
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 the
framework 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
o

Need to return the type of information on which the event refers to, for example,
employee, CPF, company.
The returned value can to be one of the standards that are defined in the interface
IF_HRPAYBR_EFD_CONSTANTS_C.

Log errors and warnings by using the instance of the CL_HRPAYBR_EFDF_EVENT class to
append exception and messages from message classes and define if the exception is an error
or warning.
To log general errors and warnings which are not specific from events, use the instance of the
class 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. It
mainly identifies an event type as a numerical code, and it stores the name of the class that processes
the 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:

b.
c.
d.

e.

f.

i. From 0001 to 7999: SAP namespace


ii. From 8000 to 9999: customer namespace
Start and end dates
Processing class enter a class that you created in step 3.1.
Classification there are 3 possible values:
i. Payroll events: events which will contain payroll information, e.g. S-1200
ii. 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, S2220.
Visualization there are 2 possible values:
i. Detailed: display the event data in the log in a detailed mode, respecting the table
which 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.
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 class


implementation
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 PROCESS
Example of implementation using default selection
METHOD 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 instance
CREATE OBJECT lo_event
EXPORTING
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 table
APPEND lo_event TO mt_events.
ENDMETHOD.
Example of implementation with employee selection
METHOD if_hrpaybr_efdf_data_extractor~process.
DATA
DATA
DATA
DATA
DATA
DATA

lv_pernr
lt_pernr_table
lr_data
lo_event
lo_ee_selection
lo_employee

TYPE
TYPE
TYPE
TYPE
TYPE
TYPE

pernr_d.
hrpay99_pernr_table.
REF TO <structure of the event>.
REF TO cl_hrpaybr_efdf_event.
REF TO cl_hrpaybr_efdf_ee_selection.
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
CHANGING
cs_data
= lr_data->* ).

Create the event instance


CREATE OBJECT lo_event
EXPORTING
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 table


APPEND 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
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA

lv_pernr
lv_cpf
ls_cpf_event
lt_pernr_table
lr_data
lo_event
lo_ee_selection
lo_employee
lo_master_data

TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE

pernr_d.
pbr_cpfnr.
gty_s_cpf_event.
hrpay99_pernr_table.
REF TO <structure of the event>.
REF TO cl_hrpaybr_efdf_event.
REF TO cl_hrpaybr_efdf_ee_selection.
REF TO cl_hrpadbr_employee.
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 fields


READ 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 instance


CREATE OBJECT lo_event
EXPORTING
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 table


APPEND 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
CHANGING
cs_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 is


necessary
For future maintenance, it is necessary to create a new version of the processing class and delimit the
V_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 from
CL_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 the
use 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, SAP
recommends that you consider whether the information necessary is applicable to be inserted in the
framework. If so, enhance the HCM Objects framework; otherwise implement it on your processing
class.
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 code
DATA 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 instance


CREATE OBJECT lo_employee
EXPORTING
Iv_pernr = lv_pernr.
* The the infotype 0001 Casting the object returned
lo_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 subarea
ls_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.