Skip to content

CloudPay Secure File Transfer Protocol (SFTP) Integration

This page includes the development guidelines and important design decisions about the implementation of the SFTP Integration to the CloudPay payroll vendor.

General Information

  • Following values must be pre-configured at CloudPay before integration.

    • Cost Centre
    • Department
    • Working Pattern with Contracted Weekly Hours
    • Employee Grade - mapped as Default
    • Leaving Reasons
    • Pay Code
  • Payroll ID given by CloudPay is based on the Company, Country and Pay Frequency.

    • Pay Frequency is mapped with the Pay Frequency of the basic salary of an employee for a particular period.
    • Pay Frequencies/ Payroll types supported by CloudPay. Weekly, Biweekly, Semi Monthly, Four Weekly, Monthly, Bimonthly, Quarterly, Semi Annual, Annual
  • Employee Salary Rates supported by CloudPay.

    • Annual Salary, Monthly Rate, Weekly Rate, Hourly Rate, Daily Rate.
  • Event types handled through integration.

    • NEW_HIRE - This event type is used at the time of a new employee creation. It is mandatory to have the event type set as NEW_HIRE for an employee to be successfully imported into CloudPay database as a new employee.
    • TERMINATION - Use this event type on a termination of an employee.
    • TRANSFER_SLE_IN - This event type is used when an employee is moving from one payroll to another within the Same Legal Entity. This event moves the employee and existing records into the new payroll. This event gets triggered when the pay frequency of the employees’ basic salary is changed.
  • CloudPay does not recommend operation type DELETE. If you want to delete a record, add a new record instead with a new validity period.

  • An employee to be treated as CloudPay Employee, following should be defined in the application.

    • Define a payroll Provider as CloudPay.
    • Define Basic Salary that matches with the pay frequency of the Payroll ID.

Limitations

  • During an implementation, where there are existing employees already uploaded in IFS cloud, integration will not be applicable for those employees. (This is due to the implementation approach of CloudPay which expects employees to have all start dates of employee master data related entities (ex. Address, Position, Cost center etc.) to be equal to date of join, which is not the case in all business scenario).

Therefore, existing employees should be uploaded to CloudPay system manually as per CloudPay instructions and then they need to be marked as Enrolled in Payroll in IFS Cloud. Integration will take place for all the new employees who joined after the integration is configured.

Above mentioned limitations have no impact on transferring employee data modifications and authorized transactions once the employee is successfully imported to CloudPay database.

  • CloudPay has a limitation when using 9999-12-31 as the end date for Employee Payment Information validity period. Hence users should not set the end date with 9999-12-31 and instead they should save a future date within 100 years from the current date as the valid to date when setting up bank information for an employee.

  • Transfer to Payroll value will be always set as true. (if the payroll provider is CloudPay)

  • Transfer to Payroll toggle in employee basic salary window will not be allowed to set / change as false (for employees marked CloudPay as the Payroll provider) due to the limitation from Cloudpay where they do not allow to maintain an employee without basic salary at any given moment.

  • Address type cannot be modified in the Payroll Integration Setup (in order to maintain the consistency in the integration setup of existing employee profiles and new employee profiles).

  • CloudPay handle all the payments in a single currency for all the employees (All the travel expenses, basic salary and additional payments should be in the same currency as currency information is not transferred in the integration except payment information).

Employee Master Data Generation

Employee Master Data generation logic is mainly written in the CloudPayEmployeeUtil utility file under PERSON component.

  • Address Details: Address Type must match with the address type defined under Payroll Integration Setup and address type should be marked as a default address type.
  • Cost Center Details: Fetch the cost center value, if there is already a cost center connected to the Primary Organization Code. If not fetch the Primary Organization Code. Cost Center percentage will always be 100%.
  • Department Details: Only Primary Organization Codes are taken into consideration when sending Department information. Department Percentage will always be 100%.
  • Salary Details: Employee Grade is set as ‘DEFAULT’ always.
  • Contract Details: If there is at least one record under job details for an employee job title will be sent. If no record found, logic for job title will be entirely based on the position title of the primary organization code.
  • Working pattern Details: Change in Contracted Weekly Hours should be done manually as it is predefined. Will not be handled through integration.
  • Payment Elective Details (Bank Information): File Types supported through integration are NON_FILE and Generic. Transaction Type supported through integration are CASH, CHEQUE and TRANSFER.
  • Changes to Valid To date will not be sent to CloudPay as additions or modifications other than Payment Electives when sending employee master data.
CloudPay XML Tag / Field Name Field included in XML (Y/N)
EMPLOYEESTATUS Y
EventType Y
HireDate Y
TerminationDate Y
TerminationReason Y
LastWorkingDate N
PERSONALDETAILS Y
EffectiveDate Y
NewEmployeeNumber N
Title N
FirstName Y
LastName Y
MiddleName Y
MaidenName Y
KnownAs Y
DateOfBirth Y
Gender Y
MaritalStatus N
Nationality Y
SecondNationality N
ADDRESSDETAILS Y
OperationType Y
EffectiveDate Y
HomePhoneNumber N
PhoneNumber N
EmailAddress N
AddressLine1 Y
AddressLine2 Y
AddressLine3 Y
City Y
County Y
State Y
Country Y
PostalCode Y
CONTRACTDETAILS Y
OperationType Y
ContractStartDate Y
JobTitle Y
PositionTimeType Y
WorkType Y
OriginalHireDate N
ProbationEndDate N
SALARYDETAILS Y
OperationType Y
SalaryStartDate Y
AnnualSalary Y
MonthlyRate Y
WeeklyRate Y
HourlyRate Y
DailyRate Y
EmployeeGrade Y
SalaryComponents N
PaymentElective Y
OperationType Y
EffectiveDate Y
ElectiveAlias Y
FileType Y
TransactionType Y
EffectiveFrom Y
EffectiveTo Y
DefaultAmount Y
DefaultValueType Y
Rank Y
BeneficiaryAccountAlias N
BeneficiaryAccountType N
BeneficiaryAccountCurrency Y
BeneficiaryAccountName N
BeneficiaryAccountNumber Y
BeneficiaryAccountRollNumber N
BeneficiaryAccountIBANNumber Y
BeneficiaryAccountRoutingCode Y
BeneficiaryAccountSWIFTCode Y
BeneficiaryAcountCheckDigit N
BeneficiaryAccountReference N
BeneficiaryBankName Y
BeneficiaryBankBranchID Y
BeneficiaryBankAddressBuildingName N
BeneficiaryBankAddressBuildingNumber N
BeneficiaryBankAddressStreet N
BeneficiaryBankAddressCity N
BeneficiaryBankAddressCounty N
BeneficiaryBankAddressState N
BeneficiaryBankAddressPostalCode N
BeneficiaryBankAddressCountry Y
Intermediary Account/ Bank fields N
Beneficiary Cheque fields N
COSTCENTERDETAILS Y
OperationType Y
EffectiveDate Y
CostCenter Y
Percentage Y
DEPARTMENTDETAILS Y
OperationType Y
EffectiveDate Y
Department Y
Percentage Y
LineManagerName N
IsApprover N
LOCATIONDETAILS N
WORKINGPATTERNDETAILS Y
OperationType Y
EffectiveDate Y
WorkingPattern Y
ContractedWeeklyHours Y
FtePercentage N
HOLIDAYENTITLEMENTDETAILS N
IDNUMBERDETAILS N
EMPLOYMENTPROPERTIES N
DEPARTMENTSMANAGED N
GLCATEGORYDETAILS N

Transfer Employee Master Data to CloudPay can be done through,

  1. New Employment Assistant - If there is a Payroll ID defined, Employee Master Data will be transferred at the time of employee creation. Employee Payroll Transfer Status will be changed to Transferred.
  2. Employees Overview - Create an employee will all mandatory fields along with a Payroll ID. Click on Transfer to Payroll. Payroll Transfer Status will be changed to Transferred. Implemented only for single company scenario.

  3. The generated file can be accessed through Application Messages. Go to Application Messages and search for sender CLOUDPAY_SENDER.

  4. Status of the file transfer can be viewed through Application Messages.
  5. If errors exist for file transfer, they will be displayed in CloudPay Analytics Tool.
  6. Payroll Transfer Status needs to be changed to Enrolled after the employees are successfully imported to CloudPay. You will be provided with a preprocessed report by CloudPay along with the Employee Details in an email.

Payment Data Generation

Payment Data generation logic is mainly written in the ExtPayrollIntCloudPay utility file under PAYINT component.

  • Payment file consists of there pay elements

    1. PermanentPayElement - Used to create/change/end recurring pay elements for an employee. The value/percentage provided will be paid once per period. Consist of Employee Additional Payments.

      Salary Period of additional payment transactions equal to the Pay frequency of the payroll ID will be handled through integration.

      Additional payment transactions marked as Transfer To Payroll “true” under employee salary information will be handled through Integration.

    2. TemporaryPayElement - Use to add/change one-time pay elements for an employee. Consist of authorized travel expenses.

    3. TimeBasedPayElement - Use to add/change time-based pay elements for an employee. Consist of authorized time records.

    4. Employee Payroll Transfer Status must be Enrolled before transferring payment data.
    5. Operation types ADD and MODIFY will only be handled through the Payment File.
CloudPay XML Tag/Field Field Included in XML (Y/N)
< PERMANENTPAYELEMENT > Y
OperationType Y
PayCode Y
Value/ Percentage Y
StartDate Y
EndDate Y
CostCenterDistribution N
< TEMPORARYPAYELEMENT > Y
OperationType Y
PayCode Y
Value/ Percentage Y
EffectiveDate Y
CostCenterDistribution Y
< TIMEBASEDPAYELEMENT > Y
OperationType Y
RateId Y
Type Y
Format Y
Value Y
EffectiveDate Y
BaseRate N
ShiftCode N
DateType Y
CostCenterDistribution Y
  • Its mandatory to define the wage type payroll value as “addition” o “Deduction” for the wage codes which will be send to CloudPay in the “time based payments” XML Section.

Employee Master File - XML File Field Mapping

In order to generate employee file at Payroll, following mandatory fields should be filled in the XML file.

Valid From Date of the first records of any detail category should be the same as Employment Start Date at Employee File > Employment > Periods page.

XML Section XML Tag Tag Mandatory in CloudPay? Included in XML file? IFS Logical Unit IFS Attribute Navigation Path to the Page
EMPLOYEESTATUS Y Y
EventType Y Y
HireDate Y Y EmpEmployedTime DateOfEmployment Employee File>Employment Information>Periods
TerminationDate Y if EventType = TERMINATION Y DateOfLeaving
TerminationReason Y if EventType = TERMINATION Y LeavingCauseType Employee Management> Terminated Employment
LastWorkingDate N N
PERSONALDETAILS Y if EventType = NEW_HIRE Y
EffectiveDate Y Y EmpEmployedTime DateOfEmployment of the first employment Employee File>Employment Information>Periods
NewEmployeeNumber N N Pers Employee File>Personal Information
Title N N
FirstName Y if EventType = NEW_HIRE Y Name1
LastName Y if EventType = NEW_HIRE Y Name4
MiddleName Y if EventType = NEW_HIRE Y Name2
MaidenName N Y Name5
KnownAs N Y Name6
DateOfBirth Y if EventType = NEW_HIRE Y DateOfBirth
Gender Y if EventType = NEW_HIRE Y Gender
MaritalStatus N N
Nationality N Y Citizenship
SecondNationality N N
ADDRESSDETAILS Y if EventType = NEW_HIRE Y
OperationType Y Y PersonInfoAddress Employee File> Personal Information>Private Contact Information
EffectiveDate Y Y ValidFrom
HomePhoneNumber N N
PhoneNumber N N
EmailAddress IN PART (If the company is enabled for ESS auto enrolment, then EmailAddress is Mandatory) N
AddressLine1 Y Y Address1
AddressLine2 N Y Address2
AddressLine3 N Y Address3
City Y Y City
County N Y County
State N Y State
Country Y Y Country
PostalCode N Y ZipCode
CONTRACTDETAILS Y
OperationType Y Y EmpJobAssign / CompanyPersAssign
ContractStartDate Y Y ValidFrom Employee File> Employment Information>Assignment>Job Details / Employee File> Employment Information>Assignment>Organizations
JobTitle Y Y JobTitle/PositionTitle
PositionTimeType Y Y Mapped to
Employment Type/Degree of Occupation/Assignment Type
WorkType Y Y Mapped to Employment Type/Assignment Type
OriginalHireDate N N
ProbationEndDate N N
SALARYDETAILS Y if EventType = NEW_HIRE Y
OperationType Y Y EmpSalaryInfo Employee File> Compensation
SalaryStartDate Y Y ValidFrom
AnnualSalary IN PART Y Amount
MonthlyRate IN PART Y
WeeklyRate IN PART Y
HourlyRate IN PART Y
DailyRate IN PART Y
EmployeeGrade Y Y Mapped to Defualt Value - Default
SalaryComponents N N
PAYMENTELECTIVE N Y
OperationType Y Y EmpPaymentInfo Employee File> Compensation>Payment Information
EffectiveDate Y Y ValidFrom
ElectiveAlias N Y EmpNo||'-'||SeqNo
FileType Y Y Enmuerated List (NON_FILE, GENERIC) depend on PayMethodDb
TransactionType Y Y PayMethodDb
EffectiveFrom Y Y ValidFrom
EffectiveTo Y Y ValidTo
DefaultAmount M if DefaultValueType = FIXED_AMOUNT or PERCENT_TOTAL Y Amount/Percentage
DefaultValueType Y Y ValueTypeDb
Rank Y Y Rank
BeneficiaryAccountAlias N N
BeneficiaryAccountType N N
BeneficiaryAccountCurrency Y Y CurrencyCodeDb
BeneficiaryAccountName BANK FILE SPECIFIC N
BeneficiaryAccountNumber BANK FILE SPECIFIC Y AccountNumber
BeneficiaryAccountRollNumber BANK FILE SPECIFIC N
BeneficiaryAccountIBANNumber BANK FILE SPECIFIC Y AccountNumber
BeneficiaryAcountCheckDigit BANK FILE SPECIFIC N
BeneficiaryAccountReference BANK FILE SPECIFIC N
BeneficiaryBankBranchID N Y Branch
BeneficiaryBankAddressBuildingName N N
BeneficiaryBankAddressBuildingNumber N N
BeneficiaryBankAddressStreet N N
BeneficiaryBankAddressCity N N
BeneficiaryBankAddressCounty Y N
BeneficiaryBankAddressState N N
BeneficiaryBankAddressPostalCode N N
BeneficiaryBankAddressCountry N Y CountryCodeDb
Intermediary Account/ Bank fields N N
Beneficiary Cheque fields N N
BeneficiaryAccountRoutingCode BANK FILE SPECIFIC Y Bank Details RoutingCode
BeneficiaryAccountSWIFTCode BANK FILE SPECIFIC Y BicCode
BeneficiaryBankName N Y Name
COSTCENTERDETAILS Y if EventType = NEW_HIRE Y
OperationType Y Y company_pers_assign Employee File> Employment Information>Assignment
EffectiveDate Y Y ValidFrom
CostCenter Y Y Connected Cost Center to OrgCode/OrgCode
Percentage Y Y Mapped to Default Value (100%)
DEPARTMENTDETAILS Y if EventType = NEW_HIRE Y
OperationType Y Y company_pers_assign Employee File> Employment Information>Assignment
EffectiveDate Y Y ValidFrom
Department Y Y OrgCode
Percentage Y Y Mapped to Default Value (100%)
LineManagerName N N
IsApprover N N
LOCATIONDETAILS N N
WORKINGPATTERNDETAILS Y if EventType = NEW_HIRE Y
OperationType Y Y work_shed_assign Employee File> Employment Information>Schedule
EffectiveDate Y Y ValidFrom
WorkingPattern Y Y DaySchedCode
ContractedWeeklyHours N Y day_shed_type WorkHoursWeek
FtePercentage N N
HOLIDAYENTITLEMENTDETAILS N N
IDNUMBERDETAILS N N
EMPLOYMENTPROPERTIES N N
DEPARTMENTSMANAGED N N
GLCATEGORYDETAILS N N

Important Decisions on Field Mapping

  • Job assignment or Position Assignment is the key attribute when sending contract details. Priority will be given to Job assignment and if it is not available position assignment will be sent.
  • If Employment Type, Assignment Type and Degree of Occupation are defined values will be selected based on the mapping done at Payroll Integration Page.
  • Only one basic salary can be defined. Based on the pay frequency defined for basic salary, payroll ID will be generated for the employee. Pay period amount will be sent with the Employee Master File.
  • Schedule ID will be sent as Working Pattern. Number of normal hours per week will be configured at Payroll Vendor.
  • Once above data is set and saved Employee File will be updated with Payroll ID at Employees > Payroll ID column.
  • Any changes to above fields will be sent to Payroll automatically.

Payment File - XML File Field Mapping

Main Tags

Operation Description Comments
ADD Insert a new record in CloudPay with the given effective date based on the record type New record (Time, Expense, Additional payment)
MODIFY Update the contents of an existing record in CloudPay using a combination of the Employee ID, Effective Date, and Pay Code to identify the record Modify record (available only for Additional payments)
DELETE Delete an existing record from CloudPay based on the unique key(s) provided for the record Not considered for integration
NONE Record will be treated as UPSERT. If the data is not present, or different from the supplied data, it will be inserted or updated in CloudPay Not considered for integration

XML Header

XML Section XML Tag Data type Comments
File header Version Decimal Same value 2.1
Unique file identifier Alphanumeric (100) This will be a combination
ExtractFromDate DateTime File created time
Employee group PayrollId Integer Selected Payroll ID in the transfer to payroll wizard

Main Sections

Permanent Pay Element (Additional pay records in the employee salary tab)

This will fetch the records which has the same salary period as the pay frequency of the basic salary. If the preliminary or amended records exists for the transferring period, then those will be fetched for the XML.

XML Tag Data type Comments
OperationType Enumerated List Value of the "File status" in the additional payment record will be mapped.
Preliminary --> ADD
Amended --> MODIFY
Transferred --> Will not be transferred
PayCode Pre-defined list Value in the "Wage code" column in employee additional payments
Value Decimal (10,2) Value in the "Amount" column in employee additional payments
StartDate Date Value in the "Valid from" column in employee additional payments
EndDate Date Value in the "Valid to" column in employee additional payments

Temporary Pay Element (Authorized travel expenses)

This contain the travel expenses related payments.

XML Tag Data type Comments
OperationType Enumerated List This value always will be ADD
PayCode Pre-defined list Value of the "Wage code" column in payroll transactions
Value Decimal (10,2) Value of the "Price x Qty" in payroll transactions
EffectiveDate Date Value of the "Start date" of Transfer period column in payroll transactions
CostCenterDistribution XML Section Cost center information

Time Based Pay Element (Authorized time transactions)

Employee time transactions will be sent as hours.

XML Tag Data type Comments
OperationType Enumerated List This value always will be ADD
RateID Pre-defined list Value of the "Wage code" column in payroll transactions
Type Enumerated list Mapped value of the "Wage type payroll" of the connected wage code
Addition --> PAYMENT
Deduction --> DEDUCTION
Format Enumerated List HOURS_DECIMAL is sent as IFS Cloud allow to save data in the same format.
Value Decimal (19,6) Value of the "Hours" column in payroll transactions
EffectiveDate Date Value of the "Start date" of Transfer period column in payroll transactions
DateType Enumerated List Mapped value of the "Transfer option" of the connected wage code
No Transfer --> Records will not be transferred
Transfer day by day --> DATE_OF
Transfer day by day only differing org code --> DATE_OF
Transfer as absence --> DATE_OF
Transfer grouped by org code --> PERIOD_COMMENCING
Transfer as absence periods --> PERIOD_COMMENCING
CostCenterDistribution XML Section Cost center information

Common Sections - Cost Center Distribution

XML Tag Data type Comments
CostCenter Predefined List Value of the "Organization code" connected for "Organization" column in payroll transactions
Percentage Decimal (3,2) Static value of 100