Representational State Transfer (REST) API Integration¶
This page includes the development guidelines about the Payroll integration using REST APIs.
General Information¶
Payroll Provider should be defined under Payroll Providers page (Human Capital Management > HCM Services > Payroll Interface > Payroll Providers) at IFS before integration.
Following values should be defined at third party Payroll Provider's side before integration,
- Company
- Cost Centre
- Departments
- Wage Codes
- Employee Category
- Positions
- Jobs
For an Employee to be connected to a Payroll Provider, the corresponding Payroll Provider should be defined for the Employee. The page to connect payroll providers to the employee is Human Capital Management > HCM Services > Employee Management > Employee File > Compensation > Payroll Provider.
Employee General Access (not to the access attribute level) is used to retrieve master data endpoint and payroll transaction endpoint.
Get Employee Master Data¶
Employee Master Data structures are defined in the EmployeeMasterDataUtil fragment file under the PERSON component.
Get Employee Master Data logic is mainly written in the EmployeeMasterDataUtil utility file under the PERSON component.
Get Employee Master Data endpoint is defined in the EmployeeMasterDataService projection file under the PERSON component.
Payroll provider will be able to get employee information including salary information (basic salary, allowances and increments) using the employee master data endpoint.
Structures in Employee Master Data¶
- EmployeeStructure - Main structure to load the employee information filtered by payroll provider and company.
- CompanyEmpStructure - Main structure to load employee information filtered by company and employee.
- AddressStructure - Structure to load address of an employee.
- OfficeStructure - Structure to load office address of an employee.
- CommMethodStructure - Structure to load the contact methods of an employee.
- PositionStructure - Structure to load the employee position information.
- EmploymentPeriodStructure - Structure to load the employment periods of an employee.
- RelativeStructure - Structure to load related persons of the employee.
- PropertyStructure - Structure to load employee properties.
- JobStructure - Structure to load the employee job information.
- SalaryInfoStructure - Structure to load the employee salary information.
- DependentStructure - Structure to load employee dependents.
- ReductionStructure - Structure to load reductions of an employee.
- ScheduleStructure - Structure to load the schedule information of an employee.
- PropertyMultiFieldStructure - Structure to load multi properties.
- MultiFieldPropertyRecordStructure - Structure to load multi field properties.
- BankDetailStructure - Structure to load employee payment information.
- EmploymentAgreementStructure - Structure to load the employee agreement information.
- EmpSalaryRateStructure - Structure to load employee salary rates.
- EmpIdentifierStructure - Structure to load employee identifier information (Available in GetCompanyEmployeeData endpoint).
- EmpPayrollProviderStructure - Structure to load employee payroll provider information (Available in GetCompanyEmployeeData endpoint).
For more information, refer to the API documentation of the EmployeeMasterDataService projection.
Get Employee Master Data Endpoint¶
The GetEmployeeMasterData function in the EmployeeMasterDataService integration projection is used to retrieve Employee Master Data.
| Function Parameter | Data Type |
|---|---|
| PayrollProviderId | Text |
| CompanyId | Text |
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ **GetEmployeeMasterData** ( **PayrollProviderId** ='ABCPAYROLL', **CompanyId** ='XYZ')
If CompanyId is passed as null, then the payroll provider can get all the employees connected to the payroll provider without filtering by company.
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ **GetEmployeeMasterData** ( **PayrollProviderId** ='ABCPAYROLL', **CompanyId** =null)
Get Company Employee Master Data Endpoint¶
The GetCompanyEmployeeData function in the EmployeeMasterDataService integration projection is used to retrieve Employee Master Data filtered by the Company Id and the Employee Id.
| Function Parameter | Data Type |
|---|---|
| CompanyId | Text |
| EmpNo | Text |
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ GetCompanyEmployeeData ( CompanyId='50', EmpNo='2005')
By passing EmpNo as null, the payroll provider can get information of all the employees filtered by the company.
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ **GetCompanyEmployeeData **( **CompanyId**='50', **EmpNo**=null)
By passing CompanyId as null, the payroll provider can get information of all the employees filtered by the EmpNo, irrespective of the company.
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ **GetCompanyEmployeeData **( **CompanyId**=null, **EmpNo**='1001')
By passing both CompanyId and EmpNo as null, the payroll provider can get information of all the employees.
Example: /int/ifsapplications/projection/v1/EmployeeMasterDataService.svc/ **GetCompanyEmployeeData **( **CompanyId**=null, **EmpNo**=null)
Get Payment Data¶
Payroll transaction structure is defined in the ExtPayrollTransUtil fragment file under the PAYINT component.
Get Payroll transaction logic is mainly written in the ExtPayrollTransUtil utility file under the PAYINT component.
Get Payroll transaction endpoint is defined in the PayrollTransactionService projection file under the PAYINT component.
Structures in Payment Data¶
- PayrollStructure - Structure to load payroll transactions.
For more information, refer to the API documentation of the PayrollTransactionService projection.
Get Payroll Transactions Endpoint¶
The GetPayrollTransactions function in the PayrollTransactionService integration projection is used to retrieve Payroll Transaction Data.
| Function Parameter | Data Type |
|---|---|
| PayrollProviderId | Text |
| ValidFrom | Date |
| ValidTo | Date |
Example: int/ifsapplications/projection/v1/PayrollTransactionService.svc/ **GetPayrollTransactions** ( **PayrollProviderId** ='ABCPAYROLL', **ValidFrom** =2020-11-01, **ValidTo** =2020-11-30)
Get Employee Absence Data¶
Employee Absence Data structures are defined in the EmployeeAbsenceDataUtil fragment file under the TIMREP component.
Get Employee Absence Data logic is mainly written in the EmployeeAbsenceDataUtil utility file under the TIMREP component.
Get Employee Absence Data endpoint is defined in the EmployeeAbsenceDataService projection file under the TIMREP component.
Payroll provider will be able to get employee absence registrations and absence periods using the employee absence data endpoint.
Structures in Employee Absence Data¶
- AbsenceStructure - Structure to load absence registrations.
- PeriodStructure - Structure to load absence periods(absence division periods).
For more information, refer to the API documentation of the EmployeeAbsenceDataService projection.
Get Employee Absence Data Endpoint¶
The GetEmployeeAbsenceData function in the EmployeeAbsenceDataService integration projection is used to retrieve Employee Absence Data.
| Function Parameter | Data Type |
|---|---|
| PayrollProviderId | Text |
| CompanyId | Text |
| DateFrom | Date |
| DateTo | Date |
| AbsenceTypeId | Text |
Example: int/ifsapplications/projection/v1/EmployeeAbsenceDataService.svc/ **GetEmployeeAbsenceData**(**PayrollProviderId**='ABCPAYROLL',**CompanyId**='XYZ',**DateFrom**=2021-01-01,**DateTo**=2021-01-31,**AbsenceTypeId**='ABC')
If CompanyId is passed as null, then the payroll provider can get all absence registrations connected to the payroll provider without filtering by company.
Example: int/ifsapplications/projection/v1/EmployeeAbsenceDataService.svc/ **GetEmployeeAbsenceData**(**PayrollProviderId**='ABCPAYROLL',**CompanyId**=null,**DateFrom**=2021-01-01,**DateTo**=2021-01-31,**AbsenceTypeId**='ABC')
If AbsenceTypeId is passed as null, then the payroll provider can get all absence registrations connected to the payroll provider without filtering by absence type.
Example: int/ifsapplications/projection/v1/EmployeeAbsenceDataService.svc/ **GetEmployeeAbsenceData**(**PayrollProviderId**='ABCPAYROLL',**CompanyId**='XYZ',**DateFrom**=2021-01-01,**DateTo**=2021-01-31,**AbsenceTypeId**=null)