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).

• IFS allows to store up to 35 characters maximum for ZIP Code in both employee address & employee bank information. However, Cloudpay supports only up to a maximum of 32 characters.

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.
• Identifier Details: Only the primary identifier for the employee would be sent, and Cloudpay will only accept the pre-defined identifier types in IFS. If users create a new identifier type and update it in employee or person files, those will be sent to CloudPay but will not be acknowledged.
• Payment Elective Details (Bank Information): Although any file type and pay method is supported in the integration, only the file types and pay methods supported by Cloudpay will be acknowledged by them.
• Payment Elective Details will only be sent to Cloudpay if purpose is 'Payroll' or 'Payroll and Payment'.
• When both routing code and sort code are defined in payment information, only sort code will be sent in payment elective details.
• Irrespective of which column the IBAN value is stored (Account number or Iban account number), Iban values will always be mapped to the BeneficiaryAccountIBANNumber xml tag.
• Changes to Valid To date will not be sent to CloudPay as additions or modifications other than Payment Electives when sending employee master data.
• For both Address details and Payment elective details, state will be sent only for the following countries; Australia (AU), Canada (CA), Switzerland (CH), Germany (DE), United States of America (US).

CloudPay XML Tag / Field Name	Field included in XML (Y/N)
EMPLOYEEGROUP	Y
PayrollId	Y
EMPLOYEEDATA	Y
EmployeeNumber	Y
EMPLOYEESTATUS	Y
EventType	Y
HireDate	Y
TerminationDate	Y
TerminationReason	Y
LastWorkingDate	N
TransferDate	Y
PERSONALDETAILS	Y
OperationType	Y
EffectiveDate	Y
NewEmployeeNumber	N
Title	Y
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	N
DefaultAmount	Y
DefaultValueType	Y
Rank	Y
BeneficiaryAccountAlias	N
BeneficiaryAccountType	Y
BeneficiaryAccountCurrency	Y
BeneficiaryAccountName	Y
BeneficiaryAccountNumber	Y
BeneficiaryAccountRollNumber	Y
BeneficiaryAccountIBANNumber	Y
BeneficiaryAccountRoutingCode	Y
BeneficiaryAccountSWIFTCode	Y
BeneficiaryAccountCheckDigit	Y
BeneficiaryAccountReference	Y
BeneficiaryBankName	Y
BeneficiaryBankBranchID	Y
BeneficiaryBankAddressBuildingName	Y
BeneficiaryBankAddressBuildingNumber	Y
BeneficiaryBankAddressStreet	Y
BeneficiaryBankAddressCity	Y
BeneficiaryBankAddressCounty	Y
BeneficiaryBankAddressState	Y
BeneficiaryBankAddressPostalCode	Y
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	Y
OperationType	Y
Value	Y
IDNumberType	Y
EffectiveFrom	Y
EffectiveTo	Y
Issuer	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
EMPLOYEEGROUP		Y	Y
	PayrollId	Y	Y	CloudPayIdInfo	PayrollId	Payroll Integration setup >> Payroll ID section >> Payroll ID
EMPLOYEEDATA		Y	Y
	EmployeeNumber	Y	Y	CompanyPerson	EmpNo	Employee ID
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
	TransferDate	Y if EventType=TRANSFER_SLE_IN	Y	EmpSalaryInfo	ValidFrom	Employee Management > Compensation > Employee Salary Information
PERSONALDETAILS		Y if EventType = NEW_HIRE	Y
	OperationType	Y	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	Y		Name3(Prefix)
	FirstName	Y if EventType = NEW_HIRE	Y		Name1(First Name)
	LastName	Y if EventType = NEW_HIRE	Y		Name4(Last Name)
	MiddleName	Y if EventType = NEW_HIRE	Y		Name2(Middle Name)
	MaidenName	N	Y		Name5(Birth Name)
	KnownAs	N	Y		Name6(Alias)
	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
	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	Y		AccountTypeDb
	BeneficiaryAccountCurrency	Y	Y		CurrencyCodeDb
	BeneficiaryAccountName	BANK FILE SPECIFIC	Y		AccountName
	BeneficiaryAccountNumber	BANK FILE SPECIFIC	Y		AccountNumber
	BeneficiaryAccountRollNumber	BANK FILE SPECIFIC	Y		AccountRollNumber
	BeneficiaryAccountIBANNumber	BANK FILE SPECIFIC	Y		AccountNumber, IbanAccountNumber
	BeneficiaryAcountCheckDigit	BANK FILE SPECIFIC	Y		AccountCheckDigit
	BeneficiaryAccountReference	BANK FILE SPECIFIC	Y		Reference
	BeneficiaryBankBranchID	N	Y		Branch
	BeneficiaryBankAddressBuildingName	N	Y		AddressLine1
	BeneficiaryBankAddressBuildingNumber	N	Y		AddressLine2
	BeneficiaryBankAddressStreet	N	Y		AddressLine3
	BeneficiaryBankAddressCity	N	Y		City
	BeneficiaryBankAddressCounty	N	Y		County
	BeneficiaryBankAddressState	N	Y		State
	BeneficiaryBankAddressPostalCode	N	Y		ZipCode
	BeneficiaryBankAddressCountry	Y	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	Y
	OperationType	N	Y	PersonIdentifier		Employee File> Personal Information
	Value	N	Y		IdentifierNumber
	IDNumberType	N	Y		IdentifierType
	EffectiveFrom	N	Y		ValidFrom
	EffectiveTo	N	Y		ValidTo
	Issuer	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