Before you can export data from Sage People HCM to a download file you must define a mapping between the fields in the HCM data objects and the fields in your file. Mapping enables you to:
- Select the fields providing the data you want to download from HCM.
- Name the fields in the download file in a way that is meaningful for the organization receiving the file. You do not have to retain the HCM field names.
- Set conditions for the mapping to populate fields in the download file when a condition is true.
- Set default values for download file fields when source fields are empty.
-
Set further options including:
- Date format.
- Translation handling.
- Character set.
- Multiple space to single space conversion.
- Number of digits after a decimal point.
- Padding character for fixed length fields.
- Validation.
Every field you want to download must be mapped - any fields missing from the mapping cannot appear in your downloaded file(s).
To define field mapping:
- Select the Payflow Services tab.
Sage People displays the Payflow Services Home page.
- Select the Payflow Service Name for which you want to define field mapping.
Sage People displays the Payflow Service Console for the Service.
- On the Payflow Service Console, select Configure:
Sage People displays the Configure page for the Payflow Service.
- In the Download Files section, select the Name of the file you want to map:
Sage People opens the Configure page for the file you selected.
- At the bottom of the page in the Mapping HCM to File section, select New:
Sage People displays the Mapping Configure page.
- Complete the fields as follows:
Field
Description
"The value in:" section
The source object and field.
HCM Object
Picklist. Select the picklist and choose the object that supplies the source data field:
- None
Select None if you want to include a field in the download file that always has the same value. Specify that value in Default.
- Payflow Service
- Payflow Batch
- Team member
- Employment
- Salary
- Job History
- Bonus
- Benefit
- Beneficiary
- Dependant
- Absence
- Timesheet
- Time Report
- Training
- Bank Accounts
Maps to the Bank Details object.
Picklist. The data field that supplies the source data from the object you selected in HCM Object. This is a dependent picklist with the content determined by the object you selected. Select the picklist and choose the field.
Default
Text. The value that you want to appear in the download file field if there is no value in the source object field. Specifying a default value can make it easier to identify the content of a large file containing otherwise empty fields.
You can enter:
- A text string.
- An expression using the syntax:
{!<expression>}
For example:
- {!' '}
Inserts a single space character in the download file field when the source file field contains no value.
- {!fHCM2__Home_Address_City__c}
Used as Default for the Home Address Region field, Inserts the value of the Home Address City field if no Region value is specified.
Leave blank to produce a blank in the download file when there is no value in the source field.
You can also use Default with None in HCM Object to specify a value to always appear in the download file in this field. The value can be a text string or derived from an expression. This offers an alternative to creating a dedicated formula field in your org, with the added advantage of enabling copying between orgs with a .fs file.
"is download as:" section
The destination file and field.
Download File
Picklist. The picklist lists all download files created for the Payflow Service.
If you have opened this page by selecting a file name in the Download Files section of the Payflow Service Configure page, Download File defaults to that file name.
To select a different file, select the picklist and choose the file.
Repeat
Number. Repeats each record on a new line, once for each field identified with a different Repeat number. Typically used to split long records and repeat fields (such as a unique identifier or name) to identify the partial records. Repeat offers a single file alternative to defining multiple download files to carry related information.
For example:
- A download file is set up with fields for:
- Payroll number
- Employee Name
- Bank Details (multiple fields)
- Salary Basis
- Salary Amount
- Bonus Amount
Use Repeat as follows:
- Payroll number: set Repeat to 1
- Payroll number: define a duplicate mapping, set Repeat to 2
- Employee Name: set Repeat to 1
- Bank Details (multiple fields): set Repeat to 1
- Salary Basis: set Repeat to 1
- Salary Amount: set Repeat to 2
- Bonus Amount: set Repeat to 2
This produces a download csv file with the following content for each source record:
LINE1:Payroll number,Employee Name,Bank Details,Salary Basis, ,
LINE2:Payroll number, , , ,Salary Amount,Bonus Amount - Lines contain empty fields when Repeat values set those values on another line.
- Fields not set with Repeat values are grouped on a new line in the order specified by Order and Position.
Subgroup
Picklist. Select the picklist and choose:
- Benefit
- Beneficiaries
- Beneficiary Benefit
- Absence
- Bonus
- Timesheet
- Time Report
- Bank Accounts
Download Field Name
The name you want to give the field in the download file.
Position
Number.
For fixed length records, the position of the first character of this field.
For variable length records, the position of the field in the record. Position is subsidiary to Order; fields are sorted by Order and then by Position. Lower number positions appear earlier in the record than higher number positions.
Order
Number.
The sequence in which fields are sorted in the record. Lower number orders appear earlier in the record than higher number orders. Fields are sorted by Order and then by Position.
"on condition:" section
Sets a condition that must be met before the content of the source field is downloaded.
Select Object
Picklist. The object containing the field you want to match to the given value for the condition to be met.
Select Field
Picklist. The field you want to match to the given value for the condition to be met. This is a dependent picklist with the content determined by the Object you selected.
Select Value
The value you want Select Field o match for the condition to be met.
If Select Object and Select Field are set and you leave Select Value blank, data can be included in the download file only if the value of Select Field is blank.
For logical NOT, use !
For example:
- !France specifies include data if the selected field contains any value other than "France".
- ! on its own specifies include data if the selected field contains any non-blank value.
To include the value of HCM Field (see "The value in" section above) when the value of Select Field has changed, use #:
Enter # to create a condition that assesses if the value in one field (Select Field) has changed before downloading the value in another (HCM Field).
If you use # AND check Changes Only, the value of HCM Field is included in the download if both the values in HCM Field and Select Field have changed.
Changes Only
Checkbox.
If checked, Payflow compares the value in HCM Field with the equivalent value in a previous download, and includes the new value of the field if it has changed. By default Payflow compares current values with values in the most recent batch of the previous payroll period. If the value has not changed the field displays a blank in the download file.
If unchecked, the value of HCM Field is included in the download file whether it has changed or not.
You can use this field in combination with Changes Only for the file specification. For example:
- With file level Changes Only unchecked:
- Fields with Changes Only checked show values in the download file only when the value has changed from the last download; they are otherwise blank.
- Fields with Changes Only unchecked always show values in the download file.
- With file level Changes Only checked:
- Records with no changes are not included in the download file, regardless of the field level Changes Only setting.
Ignore In Record Change
Checkbox. If checked, this field is ignored when assessing if the record has changed.
"with options:" section
Field conversion options.
Length
Number of bytes. The maximum length allowed for this field. Longer fields are truncated.
Format
Picklist. The date, decimal, and logical values you can impose on the downloaded data for this field. Select the picklist and choose the format you want the downloaded data to take.
Translate By Substrings
Checkbox. If translation is specified for this field in the Translation for this value section, this checkbox controls how the translation is applied.
If checked, the Current Value is treated as a substring within the field and is replaced with the specified Replacement wherever Current Value occurs. This can result in multiple replacements within the field. For example:
- Current Value: Doug Replacement: Douglas
Translates: Doug McDougal to: Douglas McDouglasal
If unchecked, Current Value is replaced with Replacement only when Current Value matches the complete field content.
To Upper
Check box.
If checked, lower case characters in the field are converted to upper case.
If unchecked, no case conversion is performed.
Character Set
Characters. The characters you want to allow in the field. If Character Set contains characters, only those characters are allowed to appear in the downloaded field; all other characters are removed.
Single Space
Checkbox.
If checked, multiple spaces between words are converted to a single space.
If unchecked, multiple spaces between words are preserved.
Scale
Number. The number of digits to display after a decimal point.
Left Pad Character
For fixed length fields, the character to use to pad short fields to the left to fill them to the required length.
Validation
An expression to validate the content of the downloaded field. Payflow generates a warning message if the field does not pass the validation.
Prefix
A text string to be inserted before the field data content. Prefix can include:
- More than one line: insert \r\n
- Tab markers: insert \t
Postfix
A text string to be inserted after the field data content. Postfix can include:
- More than one line: insert \r\n
- Tab markers: insert \t
New Loop After
Checkbox. Used for loops in HIPAA 834 format files and other formats where repeated blocks of the same type of data occur.
If checked, the downloaded field is treated as the last field in the current loop and a new loop is started with the next field. You must also specify a unique Record/Loop Counter to enable a count of the number of loops containing the Counter text string inserted in the file.
If unchecked, the downloaded field is treated as a field in the standard sequence within the record.
New Record After
Checkbox.
If checked, the downloaded field is treated as the last field in the current record and a new record is started with the next field. You must also specify a unique Record/Loop Counter to enable a count of the number of records containing the Counter text string inserted in the file.
If unchecked, the downloaded field is treated as a field in the standard sequence within the record. A new record is started after this field only if it is the last field in the record.
Record/Loop Counter
Text, up to 80 characters. A unique text string - for example SavingsPlan or Dependent - to associate with this field and enable Payflow to count the number of records or loops of that type added to the file. Payflow uses the text string to trigger a counter.
Use for the last field of the loop or record - the same field that has New Loop After or New Record After checked - to count once for each record.
If used for multiple fields within a record, the counter automatically sums all matching fields.
- Records with no data are not counted.
- When running a changes only download, unchanged records are not counted.
You can use the counter in a formula to return the number of records carrying the string. Typically used in a header or footer, for example:
lpad: a standard function to insert the following characters to the left of a text string.repeat a,b: a standard function to repeat a, b times - None
- If you do not want to provide a translation value for this field, select Save.
Sage People displays the Payflow Service Configure page with the mapping you defined added to the list of fields in the Mapping HCM to Download Files section.
- If you want to provide a translation value for this field, select New in the Translation for this value section.
Sage People displays the Translation Configure page.
- Complete the fields as follows:
"Translation for this value" section
Current Value
The original value in the field you want to change. See the Translate By Substrings field description for different ways of handling the translation.
Replacement
The value you want to use to substitute for Current Value. See the Translate By Substrings field description for different ways of handling the translation.
If Replacement is blank, Current Value is deleted when it is found.
- Select Save.
Sage People displays the Mapping Configure page.
- Select Save.
Sage People displays the Payflow Service Configure page with the mapping you defined added to the list of fields in the Mapping HCM to Download Files section.
