Fairsail Data Loader Implementer's Guide - Sage Peoplehelp.sagepeople.com/Fairsail Data Loader Implementer's... · · 2016-08-25Competency Competency Assessment Competency Library

FS-HCM-DL-IG-201608--R014.01

Data Loader Implementer's Guide Version 14.01

Data Loader Implementer's Guide © Fairsail 2016 2

© Fairsail 2016. All rights reserved.

This document contains information proprietary to Fairsail and may not be reproduced, disclosed, or used in whole or in part without the written permission of Fairsail.

Software, including but not limited to the code, user interface, structure, sequence, and organization, and documentation are protected by national copyright laws and international treaty provisions. This document is subject to U.S. and other national export regulations.

Fairsail takes care to ensure that the information in this document is accurate, but Fairsail does not guarantee the accuracy of the information or that use of the information will ensure correct and faultless operation of the service to which it relates. Fairsail, its agents and employees, shall not be held liable to or through any user for any loss or damage whatsoever resulting from reliance on the information contained in this document.

Nothing in this document alters the legal obligations, responsibilities or relationship between you and Fairsail as set out in the contract existing between us.

This document may contain screenshots captured from a standard Fairsail system populated with fictional characters and using licensed personal images. Any resemblance to real people is coincidental and unintended.

All trademarks and service marks mentioned in this document belong to their corresponding owners.

FS-HCM-DL-IG-201608--R014.01

Contents


Contents

Introduction 4

Upgrading an Existing Data Loader Package 6

Input file specification 7

Alternative file formats 7

Additional Guidelines 8

Using the Fairsail Data Loader 9

Creating a Template for Current Data 11

Creating a Template for Single Data Objects 14

Using Picklist Exporter 17

Uploading Current Data 20

Uploading History Data 24

Mass Data Deletion 29

Displaying Information About Data Loads 32

Using the Data Loads Tab 33

Starting a New Data Load From the Data Loads Tab 35

Using the Data Load Detail Page 36

Loading File Attachments in Bulk 40

Installing the Apex Data Loader 41

Generating a List of File Attachments 44

Using the Apex Data Loader to Insert Attachments 45

Glossary of Terms 54

Index 56


Introduction

Every new customer has a range of data to load into the Fairsail system:

Current data for team members, including name, position, manager, salary, contact details, vacation entitlement and so on.

History data for existing team members, including employment start dates, salary history, previous positions held, absence and vacation taken and so on.

This data can be held in an existing HRIS or HCM system, in spreadsheets, or in a range of formats across the customer's organization.

The Fairsail discovery process establishes customers' detailed requirements and produces templates mapping field labels, which may be customer-specific, to Fairsail API field names. Any customer-specific fields are created before data loading can start. Data loading then takes customer data, converts it to a Fairsail compatible format and uses it to populate the tables comprising the customer's Fairsail HCM system.

Fairsail Data Loader enables you to automate much of the data loading process. The Fairsail Data Loader:

Generates the templates mapping field labels to API field names.

Provides dynamic access to picklist values for building in to generated templates.

Takes formatted source files with current data for the following objects and uploads that data into Fairsail:

Team Member Employment Record Salary

Takes formatted source files with history data for the following objects and uploads that data into Fairsail:

Absence Absence Accrual Absence Accrual Pattern

Absence Accrual Rule Absence Accrual Seniority Absence Adjustment

Absence Carryover Bucket

Beneficiary Benefit Bonus

Competency Competency Assessment Competency Library

Dependants Education Emergency Contact

Employment Record Exchange Rate Experience

Job History Job Library Item Job Profile

Management/Cross Reporting Objectives Performance Review

Salary Scale Scale Response

Skill Skill Library Item Successor

Talent Plan Training Training Library Item

Work Days Holiday Work Days Pattern

Introduction Upgrading an Existing Data Loader Package


Enables uploads to be repeated.

Provides integrated reporting on the progress of each data load and access to a full history of data loads.

Data must be supplied in a standard format (see page 7), and must follow a set of rules to ensure error free data loading.

The Fairsail Data Loader also provides a Mass Deletion option to enable bulk clearance of object records. This is a powerful feature that must be used with care - deleted items cannot be retrieved! Use Mass Deletion for clearing down test environments, for deleting complete sets of records loaded in error, or for removing records found to contain large numbers of errors that are best fixed in the source before reloading (see page 29).

Introduction Upgrading an Existing Data Loader Package


Upgrading an Existing Data Loader Package

1. Use the link to the new package supplied by Fairsail and login to the org you want to upgrade.

2. Select Install for Specific Profiles.

Fairsail displays a list of available Profiles.

3. Select the picklist for Set access level for all profiles to and choose No Access.

4. Select Set.

5. In the list of Profiles select the picklists in the Access Level column and choose the following mapping:

Profile Access Level

Fairsail Administrator Full Access

Gives full access to Data Loader.

Fairsail HR Manager No Access

Fairsail Platform Team Member No Access

All other Profiles No Access

6. Select Install.

The package is installed in your org. The installation may take several minutes to complete - if a progress page is displayed, select Done.

When installation is complete, you are sent an email confirming successful installation in your org.


Input file specification

Input files for the Fairsail Data Loader must match the following specification:

Notes

Format Text, Comma-separated Value (CSV). Fields containing commas must be enclosed in double quotes.

You can optionally enclose all fields in double quotes.

Record termination Carriage return, Line Feed (CR LF). Do not include Carriage Returns in fields; these are interpreted as end of record markers.

Character encoding UTF-8 Essential if your data includes Unicode characters beyond the basic ASCII set. UTF-8 (UCS Transformation Format-8 bit) can represent every character in the Unicode character set.

First record Names of fields contained in the file. Use the API names for the fields as supplied in the customer-specific mapping templates.

Maximum file size 10,000 records. When uploading larger amounts of data, split the content over two or more files.

Alternative file formats

As alternatives to CSV format, the Fairsail Data Loader can use input files in the following formats:

Tab-separated Value (TSV)

Pipe delimited.

As with other character delimited formats, ensure that fields with the delimiting character in the field content are enclosed in double quotes to avoid those characters being interpreted as end of field markers.

Input file specification Additional Guidelines


Additional Guidelines

If you choose to create your own template files rather than using the Fairsail Template Generator, make sure that your templates follow these rules:

Field names must be separated with the field delimiter you are going to use for the data file. Use the same delimiter consistently, do not mix commas, tabs, and pipes.

Use the correct object prefixes for fields that are not Team Member object fields. This ensures that fields are correctly identified. For example, Start Date and End Date fields exist in multiple objects and must be prefixed Employment Start Date or Salary Start Date for example.

Dates must be consistently represented in either dd/mm/yyyy or mm/dd/yyyy format. Do not mix formats in a single file. The separator between date components is not important; you can use slash (/), stop (.), hyphen (-), or underscore (_). But the Fairsail Data Loader expects to find:

<2 digits><separator><2 digits><separator><4 digits>

...and will fail to load if dates do not comply.

Microsoft Excel is not ideal as an application for generating the source CSV files because:

o It has a tendency to corrupt data; for example, leading zeros are truncated from fields by default.

o Standard Excel Save As... CSV does not produce UTF-8 character encoding.

You can use an alternative spreadsheet application such as LibreOffice Calc (http://www.libreoffice.org), which enables you to avoid many of the limitations of Excel for CSV preparation.

However, if you are familiar with the potential problems of Excel and the required work-arounds, you can use Excel to template and prepare your source data for uploading:

a. Save Excel files in CSV format.

b. Open the CSV files in an application such as Notepad++ (http://notepad-plus-plus.org) or Sublime Text (http://www.sublimetext.com).

c. Save the files with UTF-8 character encoding

Many Windows programs including Microsoft Notepad add bytes at the start of a UTF-8 encoded file to produce a UTF-8 encoding of the Unicode byte order mark (BOM). Files encoded in this way are often classed as UTF-8 BOM, or UTF-8 with BOM.

The Fairsail Data Loader returns an error if you attempt to load a CSV file encoded as UTF-8 BOM. This is a common cause of data load failures - check for BOM encoding when data loads fail for no other clear reason. Pass any UTF-8 BOM files through an application such as Notepad++ or Sublime Text to strip the BOM and produce a clean UTF-8 encoded file.


Using the Fairsail Data Loader

You can use the Fairsail Data Loader to:

Generate templates for current and history data using the Fairsail Template Generator.

Templates contain the field labels and, optionally, the API field names for the data you want to upload. Templates are generated using UTF-8 character encoding, and with the field delimiters you choose. You can then use the templates as a shell to fill with the data you want to upload.

Using the Fairsail Template Generator:

o Extracts available field labels directly from the objects and enables you to select them. This simplifies the template build and avoids the risk of mis-keying.

o Ensures that field labels include the correct object prefix (Employment, Salary) when needed to uniquely identify fields.

o Enables you to add API field names to the template, ensuring selected fields are correctly mapped.

o Enables you to select key fields to fine tune data mapping for updating data.

o Enables you to use empty fields when updating records to delete existing data.

o Provides a preview of the template file before creating it, enabling you to correct any obvious errors.

o Ensures that the template file is comma-separated and UTF-8 encoded.

View and export picklist values.

Picklist values are dynamically extracted from the system, ensuring that all current customizations are visible. You can then copy the values to your data template(s) for uploading.

Upload current and history data.

You can specify the delimiter and date format used in the file to upload, and choose to insert new records or update existing records.

You must load current data first. Current data includes data for the Team Member, Employment Record, and Salary objects, and forms a base that is referenced by other objects.

Mass delete data for an object or group of related objects.

You can use mass deletion to purge test data or delete a set of data that loaded successfully but was subsequently discovered to contain multiple errors.

Browser compatibility

Fairsail Data Loader features are fully supported by the following browsers:

Apple Safari version 5 or later

Google Chrome

Microsoft Internet Explorer version 10 or later

Mozilla Firefox version 4 or later

Opera version 11 or later

Using the Fairsail Data Loader Additional Guidelines


To start the Fairsail Data Loader click the Data Loader tab:

Fairsail displays the Fairsail Data Loader home page:

Using the Fairsail Data Loader Creating a Template for Current Data


Creating a Template for Current Data

Use the Template Generator to produce a UTF-8 encoded, field delimited file that contains the field names you want to load as your current data set.

You can then use the template as a guide when adding data records exported from your current HRIS system, or created in a text editor or compatible spreadsheet package. This data can be loaded into the Team Member, Employment Record, and Salary objects. Load current data before attempting to load history data.

You can generate a template using other methods, but the Template Generator takes care of many of the requirements for you. If you are not using the Template Generator, ensure that your files match the input file specification (see page 7).

1. On the Fairsail Data Loader Home page, click Template Generator:

Fairsail displays the field selector page:

The left panel displays all the available fields from the Team Member, Employment Record, and Salary objects.

2. Select the fields in the left panel you want to add to the template:

o Use Ctrl + click to select multiple field names.

o Use click then Shift + click to select a contiguous block of field names.



3. To add the selected fields to the right template window, click the right arrow

To add all available fields to the right template window, click the right multi-arrow . It is sometimes easier to add all fields and then remove the few that you do not need.

To remove fields from the right template window, select the fields and click the left arrow

To remove all fields from the right template window, click the left multi-arrow

To sort the fields in the right template window, select the field(s) to move and click the up or

down arrows.

4. To add API field names to the template file, check Insert API Names.

API names are added as a second record to the template file. This is useful to help ensure that you have selected the correct fields.

Files for loading must contain either field labels or API field names, not both. If you insert API names, make sure you remove either the field labels or the API names before attempting to upload your data file.

5. When you have added all the fields you need to the template window, click Generate to see a preview of the file:

The preview is displayed in the preview window at the bottom of the page:

To resize the preview window, click and drag the control at the bottom right of the window:

The resize feature is not supported by all browsers.



6. When you are sure that the preview shows the correct field content in the correct order, click Create File:

You are prompted to open or save the file.

7. Click Open to view the file content in your selected application.

8. Make sure that the template file is as you want it, then save the file for use as a template.

Using the Fairsail Data Loader Creating a Template for Single Data Objects


Creating a Template for Single Data Objects

Use the Template Generator to produce a UTF-8 encoded, field delimited file that contains the field names you want to load for a single data object. Typically, this is used to create templates for loading history data. If you are loading data for multiple objects, the process is easier to manage if you create one template for each object.

You can then use the templates as a guide when adding data records exported from your current HRIS system, or created in a text editor or compatible spreadsheet package.

You can generate a template using other methods, but the Template Generator takes care of many of the requirements for you. If you are not using the Template Generator, ensure that your files match the input file specification (see page 7).

1. On the Fairsail Data Loader Home page, click Template Generator Individual Objects:

Fairsail displays the object and field selector page:

2. In Object Type, click the picklist and select the object from which you want to select the fields to be included in the template.



3. Click Populate:

Fairsail loads the available fields from the selected object in the left panel:

4. Select the fields in the left panel you want to add to the template:

o Use Ctrl + click to select multiple field names.

o Use click then Shift + click to select a contiguous block of field names.

5. To add selected fields to the right template window, click the right arrow.

To add all available fields to the right template window, click the right multi-arrow. It is sometimes easier to add all fields and then remove the few that you do not need.

To remove fields from the right template window, select the fields and click the left arrow.

To remove all fields from the right template window, click the left multi-arrow.

To sort fields in the right template window, select the field(s) and click the up or down arrows.

6. To add API field names to the template file, check Insert API Names.

API names are added as a second record to the template file. This is useful to help ensure that you have selected the correct fields.

Files for loading must contain either field labels or API field names, not both. If you insert API names, remove either the field labels or the API names before attempting to upload your data file.

7. When you have added the fields you need to the template window, click Generate to see a file preview:

The preview is displayed in the preview window at the bottom of the page:



To resize the preview window, click and drag the control at the bottom right of the window:


8. When you are sure that the preview shows the correct field content in the correct order, click Create File:

You are prompted to open or save the file.

9. Click Open to view the file content in your selected application.

10. To ensure that Fairsail can apply each record to the correct Team Member, make sure that the template includes a field for the Team Member's Unique Id. This is a unique identifier for each Team member that will not change. Unique Id has API name: fHCM2__Unique_Id__c. If you are using field labels, use the label: Unique Id.

11. Make sure that the template file is as you want it, then save the file for use as a template.

Creating a template for the Beneficiary object

The Beneficiary object has three required fields:

Unique Id of the Team Member holding the benefit.

Benefit record type of the benefit associated with the beneficiary.

Benefit start date of the benefit associated with the beneficiary.

These fields enable Fairsail to identify or create the correct record for the Beneficiary object.

When building the template, make sure you include labels for these fields in the first line of the template file like this:

Unique Id,Benefit Start Date,Benefit record type,Amount Benefit,Dependant name,Beneficiary Start Date,Beneficiary End Date

You can also include the optional field:

Dependant name

The order of the fields in the first line of the template file is not important.

Using the Fairsail Data Loader Using Picklist Exporter


Using Picklist Exporter

Picklist Exporter enables you to view and export picklist values for building in to your data templates. Follow these steps:

1. Create any new picklist fields you require and add the values you want to make available for selection.

2. Modify any existing picklist values in line with customer requirements.

3. Use Picklist Exporter to view each picklist and its associated values. Copy the values.

4. Paste the picklist values into the data template, typically on a separate sheet to act as lookup values from the main template.

To use Picklist Exporter:

1. On the Fairsail Data Loader Home page, click Picklist Exporter:

Fairsail displays the Picklist Exporter page.

2. In Object Type click the picklist and select the object for which you want to display available picklists:



Fairsail displays available picklists for that object:

3. Click the picklist for which you want to list values.

Fairsail displays the values in the right window:

o To display values for multiple picklists, use Ctrl + click:

o To resize the right window, click and drag the control at the bottom right:




4. In the right window, select the values you want to copy.

5. Right click and select Copy.

6. Paste the values into your template.

Using the Fairsail Data Loader Uploading Current Data


Uploading Current Data

Any data to be uploaded must be prepared in the correct format (see page 7). Ideally, use the Fairsail Template Generator to create the template files you use to hold the data you want to upload (see page 11).

If you create your own template files, make sure that the API field names specified in the first record of a file to be uploaded are complete with object prefixes as appropriate to ensure that fields are fully and correctly identified; for example:

Use fHCM2__Employment__c.fHCM2__Start_Date__c as an API field name, NOT just fHCM2__Start_Date__c

The procedure for uploading data for Team Member, Employment Record, and Salary data (typically, current data) differs from that for other records. You must upload current data before attempting to upload history data.

When your data file is ready:

1. On the Fairsail Data Loader Home page, click Team Member, Employment and Salary:

Fairsail displays the Team Member, Employment and Salary Combined Upload page:



2. Complete the fields as follows:

File The file you want to upload. Click Browse... to find and select the file.

Import Type Picklist. Click the picklist and select from:

Insert

To add wholly new data to Fairsail. Insert creates new records. Use Insert if the file contains just data for new team members.

Update

To modify existing records. Update adds data to existing records. Use update if the file contains just new values for existing team members.

Upsert

To add new records and modify existing records with a single file. Use Upsert if the file contains a mix of updates to existing records and new records to insert.

Delimiter Picklist. The separator used between fields in the file. Click the picklist and select from:

Comma

Tab

Pipe

Date Format Picklist. The format used to represent dates in the file. Click the picklist and select from:

dd/mm/yyyy

mm/dd/yyyy

Dates must be consistently represented in either dd/mm/yyyy or mm/dd/yyyy format. Do not mix formats in a single file. The separator between date components is not important; you can use slash (/), stop (.), hyphen (-), or underscore (_). But the Fairsail Data Loader expects to find dates represented in the form:


...and will fail to load the file if dates do not comply.

Check Only Checkbox. To validate the data file before loading.

If checked, the file is validated and not loaded. Use this setting to trap errors and fix the causes before attempting to load a file.

If unchecked, the Fairsail Data Loader attempts to load the file immediately after checking if no errors are found.



3. Click Upload.

Fairsail attempts to read the file and lists the file headers and number of rows in the File Details section:

4. In Field check:

o The correct fields are listed.

o The correct number of data records is displayed against Number of rows.



5. If Field confirms that the data file contains the data you want to load, click Import to upload the data. Otherwise, click Abort.

When importing, Fairsail displays the Data Load Detail page:

You can use the Data Load Detail page to:

o Follow the progress of the data load - see Status.

o View any errors generated as part of the data load process. The error list is loaded as a text file attachment in the Notes & Attachments related list, and also sent to the email address of the user running the upload.

o Re-run the data load.

Data Load Detail pages also provide a range of additional information and options for data loads (see page 32).

6. Open the email sent to the email address of the user running the upload.

o If errors were identified when Import ran, they are listed in an ErrorList text file attached to the Data Load Detail page in the Notes & Attachments related list, and in the email. Any errors result in an aborted upload - you must fix the cause of the errors and re-run the upload.

o If you were running a Check Only upload and no errors were found, the email subject is Check Complete and the email confirms Operation Complete and the number of rows identified in the file. You can now uncheck Check Only and re-run the upload.

o If you were running an upload with Check Only not checked and no errors were found, the email subject is COMPLETE and the email confirms Operation Complete and the number of records imported.

Using the Fairsail Data Loader Uploading History Data


Uploading History Data

Any data to be uploaded must be prepared in the correct format (see page 7). Ideally, use the Fairsail Template Generator to create the template files you use to hold the data you want to upload (see page 14).

If you create your own template files, make sure that:

Each record includes the Unique Id (fHCM2__Unique_Id__c) field to uniquely identify the Team Memberto which the record applies.

The procedure for uploading data for single objects (typically, history data) differs from that for Team Member, Employment Record, and Salary data. You must upload current data before attempting to upload history data.

Ensure that files containing history data do not contain current values as well. For example, a current salary loaded incorrectly as part of a salary history record would be stored against the same date as a current salary loaded correctly as part of an Employment record current data load, leading to duplication and potential confusion.

Uploading data for the Absence Carryover Bucket object

The Absence Carryover Bucket object has the required field:

Absence Accrual Name of the Absence Accrual associated with the Absence Carryover Bucket.

This field enables Fairsail to identify the correct record for the Absence Carryover Bucket object.

When creating the file for initial data upload using the Insert option, make sure you include:

The labels for these fields in the first line of the file:

o fHCM2__Absence_Accrual__cThe Absence Accrual Name.

o Expiry_DateThe Expiry Date of the Absence Carryover Bucket.

o AmountThe Amount of the Carry Over you want to load for the Absence Carryover Bucket.

Data for each of these fields in each record.

When updating existing data using the Update option, make sure you include:

The labels for these fields in the first line of the file:

o fHCM2__Absence_Accrual__cThe Absence Accrual Name.

o Unique IdThe name of the Absence Carryover Bucket.

o Expiry_DateThe Expiry Date of the Absence Carryover Bucket. Can be excluded if you are not updating any Expiry Datevalues.

o AmountThe Amount of the Carry Over you want to load for the Absence Carryover Bucket. Can be excluded if you arenot updating any Amount values.

Data for each of these fields in each record.



Uploading data for the Beneficiary object

The Beneficiary object has three required fields:

Unique Id of the Team Member holding the benefit.

Benefit record type of the benefit associated with the beneficiary.

Benefit start date of the benefit associated with the beneficiary.

These fields enable Fairsail to identify or create the correct record for the Beneficiary object.

When creating the file for data upload, make sure you include:

The labels for these fields in the first line of the file.

Data for each of these fields in each record along with any other data you want to load.

When your data file is ready:

1. On the Fairsail Data Loader Home page, click Individual Object:

Fairsail displays the Single Object Upload page:



2. Complete the fields as follows:

Object Type Picklist. The object you want to update with the data contained in the file.

File The file you want to upload. Click Browse... to find and select the file.

Make sure that the first field of every record in the file is the Unique Id of the Team Member to which the record applies.

Import Type Picklist. Click the picklist and select from:

Insert

To add wholly new data to Fairsail. Insert creates new records.

Update

To modify existing records. Update adds data to existing records.

Key Fields (update only)

API field names. Enables you to selectively update records based on the content of one or more key fields when the data you want to change is for a field or fields that could apply to multiple records, such as start or end dates.

Enter the API field names for the fields you want to act as key fields. There is no need to enter Unique ID or Record Type because these fields are assumed to be Key and are used by default.

For example, to update the Deduction End Date for Benefit records where the Deduction Code is DC005, enter:

fHCM2__Deduction_Code__c

as the key field. The template could include:

fhcm2__unique_id__c,fhcm2__record_type__c,fHCM2__Deduction_Code__c, fHCM2__Deduction_End_Date__c

and the upload file then contains records of the form:

001024,Benefit,DC005,30/06/2014

Delimiter Picklist. The separator used between fields in the file. Click the picklist and select from:

Comma

Tab

Pipe

Date Format Picklist. The format used to represent dates in the file. Click the picklist and select from:

dd/mm/yyyy

mm/dd/yyyy

Dates must be consistently represented in either dd/mm/yyyy or mm/dd/yyyy format. Do not mix formats in a single file. The separator between date components is not important; you can use slash (/), stop (.), hyphen (-), or underscore (_). But the Fairsail Data Loader expects to find dates represented in the form:


...and will fail to load the file if dates do not comply.

Ignore Blanks Checkbox. To determine how blank fields in the upload file are treated. Checked by default.

If checked, blank fields in the upload are ignored.

If unchecked, blank fields in the upload file overwrite existing field content with blanks.



Check Only Checkbox. To validate the data file before loading.

If checked, the file is validated and not loaded. Use this setting to trap errors and fix the causes before attempting to load a file.

If unchecked, the Fairsail Data Loader attempts to load the file immediately after checking if no errors are found.

3. Click Upload.

Fairsail attempts to read the file and lists the file headers and number of rows in the File Details section:

4. In File Details, check:

o The correct fields are listed.

o The correct number of data records is displayed against Number of rows.



5. If File Details confirms that the data file contains the data you want to load, click Import to upload the data. Otherwise, click Abort.

When importing, Fairsail displays the Data Load Detail page:

You can use the Data Load Detail page to:

o Follow the progress of the data load - see Status.

o View any errors generated as part of the data load process. The error list is loaded as a text file attachment in the Notes & Attachments related list, and also sent to the email address of the user running the upload.

o Re-run the data load.

Data Load Detail pages also provide a range of additional information and options for data loads (see page 32).

6. Open the email sent to the email address of the user running the upload.

o If errors were identified when Import ran, they are listed in the email. Any errors result in an aborted upload - you must fix the cause of the errors and re-run the upload.

o If you were running a Check Only upload and no errors were found, the email subject is No Errors and the email confirms Operation Complete and the number of rows identified in the file. You can now uncheck Check Only and re-run the upload.

o If you were running an upload with Check Only not checked and no errors were found, the email subject is Complete and the email confirms Operation Complete and the number of records imported.

Using the Fairsail Data Loader Mass Data Deletion


Mass Data Deletion

The Fairsail Data Loader provides an option for deleting uploaded data for a complete object or group of related objects. You can use this option for example:

If your data loading process includes a test data load which you subsequently need to delete.

If you discover the data you loaded contains a repeated or systemic error that has affected multiple records. It is often easier to fix the error in the file to be uploaded and then reload, having first deleted the affected data.

If you load a set of records in error.

Mass Data Deletion also provides an option for deleting Import Row data. Import Row data is data held in temporary storage that is normally deleted by the Fairsail Data Loader on completion of an upload operation. Under some

circumstances, such as an uncompleted abort or other interrupted process, temporary data may not be fully cleared.

Do not use Mass Deletion > Import Row when a data load is in progress!

Use Mass Deletion > Import Row only under direction from Fairsail.

Mass data deletion enables you to select an object and delete all the records held for that object. There is no limit on the number of records that can be deleted at one time. You are asked to confirm your deletion - there is no undo option and deleted records cannot be retrieved from the recycle bin!

To use Mass Data Deletion:

1. On the Fairsail Data Loader Home page, click Mass Deletion:

Fairsail displays the Mass Data Deletion object selector page:



For the purposes of mass deletion, objects are arranged hierarchically so that selecting an object that has fields used by another object, also selects the child object(s):

Selecting this object... ...also selects these objects

Team Member All others

Employment Record Absence

Benefit

Bonus

Job History

Salary

Absence No other

Benefit No other

Bonus No other

Dependant No other

Education No other

Emergency Contact No other

Experience No other

Job History No other

Performance Review No other

Salary No other

Skill No other

2. Check the boxes to select the object(s) for which you want to delete all records.

The display changes to show selected objects in red:

Child objects cannot be deselected without deselecting the parent object.



3. When you have selected the objects you want, click Delete:

Fairsail displays the Mass Data Deletion confirmation page:

4. Check that the objects listed are the ones for which you want to delete all records.

5. If the correct objects are listed, click I understand that this will permanently delete ALL rows for the selected objects.

Fairsail permanently deletes all records stored for the objects you selected.

6. If the list is not correct, click Abort to cancel the deletion and return to the object selector page.


Displaying Information About Data Loads

The Fairsail Data Loader:

Reports on the progress of each data load through the Data Load Detail page (see page 36).

Gives you separate access to a full history of data loads through the Data Loads tab.

The Data Loads tab also provides:

o Access to all Data Load Detail pages (see page 36).

o An alternative path to the Data Loader (see page 35).

Displaying Information About Data Loads Using the Data Loads Tab


Using the Data Loads Tab

To open the Data Loads page, click the Data Loads tab:

Fairsail displays the Data Loads Home page, defaulting to display Recent Data Loads:

To display a different subset of loads, such as those relating to a a particular object type, or with a specific status, choose - or create - a different view.



The Data Loads page displays the following information for each data load:

Field Description

Data Load Batch Id A unique identifier for the data load, created from a date and time stamp.

Click the link to display the Data Load Detail page for the data load (see page 36).

Record Type The type of data load:

Main Load

A current data load for the Team Member, Employment Record, or Salary objects.

Object Load

A history data load for a specific object.

Object Type For Object Load Record Types, the API name of the object.

For example:

fHCM2__education__c

for a data load of Education records.

Start Time The date and time (hh:mm) the data load started.

End time The date and time (hh:mm) the data load finished.

End Time is blank for data loads that are still in progress.

Status The current status of the data load:

Staging

Locating source files and preparing the data for checking. Uploads waiting for Import display as Staging.

Checking

Initial validation of the content of the source file in preparation for committing the data.

Committing

Data has passed the initial validation performed at the Checking stage and Data Loader is attempting to write the data to the database.

Completed - Errors

The data load has completed but was not successful. Errors are trapped in a separate text file and sent by email to the email address of the user running the upload. No data has been written to the database.

Completed

The data load has completed successfully without error. All data has been written to the database.

Aborted

The data load was aborted.



Starting a New Data Load From the Data Loads Tab

1. On the Data Loads Home page, click New:

Fairsail displays the New Data Load Select Data Load Record Type page:

2. In Record Type of New Record, click the picklist and select:

o Main Load to load current data for the Team Member, Employment Record, or Salary objects.

o Object Load to load history data for an individual object.

3. Click Continue.

o For a Main Load, Fairsail displays the CSV File Upload page (see page 20).

o For an Object Load, Fairsail displays the Object Upload page (see page 24).

Displaying Information About Data Loads Using the Data Load Detail Page


Using the Data Load Detail Page

The Data Load Detail page is displayed:

When you click Import in the File Details section of an upload page.

When you click a Data Load Batch Id link on the Data Loads Home page.

The Data Load Detail page displays the following information and options:

Field Description

Record Type The type of data load:

Main Load

A current data load for the Team Member, Employment Record, or Salary objects.

Object Load

A history data load for a specific object.

Click Change to change the record type for this data load.

Data Load Batch Id A unique identifier for the data load, created from a date and time stamp.

Start Time The date and time (hh:mm) the data load started.



End Time The date and time (hh:mm) the data load finished.

End Time is blank for data loads that are still in progress.

Status The current status of the data load:

Staging

Locating source files and preparing the data for checking. Uploads waiting for Import display as Staging.

Checking

Initial validation of the content of the source file in preparation for committing the data.

Committing

Data has passed the initial validation performed at the Checking stage and Data Loader is attempting to write the data to the database.

Completed - Errors

The data load has completed but was not successful. Errors are trapped in a separate text file and sent by email to the email address of the user running the upload. No data has been written to the database.

Completed

The data load has completed successfully without error. All data has been written to the database.

Aborted

The data load was aborted.

Created By The name of the user creating the data load, and the date and time of creation.

Options section

The options selected for the data load on the CSV Upload or Object Upload pages.

Object Type Displayed for Object Loads. The API name of the object to which this data load applies.

Import Type The type of data load:

Insert.

Creating new records.

Update.

Modifying existing records.

Upsert

Adding new records and modifying existing records.

Header Type Not used. Headers are automatically set to API names.

Delimiter The separator used between fields in the upload file.

Date Format The date format used in the upload file.



Check Only If checked, the data load validates the data but does not attempt to commit it to the database.

If unchecked, the data load will attempt to complete the data load to the database.

Notes & Attachments section

Action Options available for the note or attachment.

For an Error List text file you can:

Edit the file, including changing the file name.

Delete the file. You are asked to confirm deletion.

For a data file you can:

Edit information about the attachment, including the file name and description. To edit the content of the file use View.

View the content of the file in your chosen editor. You can then edit and save the file.

Delete the file. You are asked to confirm deletion.

Type Note or Attachment.

Title The file name of the note or attachment.

Click the title for an Error List text file to:

:Display the Note Detail page. You can then:

o Edit the file.

o Delete the file.

Click the title for a data file to:

Display the Attachment Detail page. You can then:

o Edit information about the file, including the file name and description.

o View the content of the file in your chosen editor. You can then edit and save the file.

o Delete the file. You are asked to confirm deletion.

Last Modified The date and time the file was last modified. For files where the upload process has finished, Last Modified is the same as End Time.

Created By The name of the user creating the data load.




Loading File Attachments in Bulk

The Fairsail Data Loader takes care of bulk data loading to set up current and history data for your Team Members. To load existing attachments to Team Member's Employment Records in bulk, you can use the Salesforce Apex Data Loader, freely available to existing Salesforce users.

This section provides need-to-know information to install and use the Salesforce Apex Data Loader for bulk loading attachments to Fairsail Employment Records.

Attachments are added to the Notes & Attachments Related List on the Team Member's Employment Record.

There are 3 steps:

1. Install the Salesforce Apex Data Loader (see page 41).

2. Generate a list of attachments as a CSV file (see page 44). Each record in the list must contain:

o An identifier for the Team Member's Employment Record. This is where each attachment is to be held. Use the unique Employment Record Id.

o The name of the file to be attached.

o The path to the attachment to tell the Apex Data Loader where each file can be found.

3. Run the Salesforce Apex Data Loader to insert the attachments in your Fairsail system (see page 45).

You can find more information about the Salesforce Apex Data Loader, including downloadable documentation, on the Salesforce.com Foundation site:

http://salesforcefoundation.screenstepslive.com/s/npsp/m/2885/l/26241-downloading-and-configuring-the-apex-data-loader



Loading File Attachments in Bulk Installing the Apex Data Loader


Installing the Apex Data Loader

1. Go to Setup > Administration Setup > Data Management > Data Loader.

Salesforce displays the Data Loader Setup page:

2. Click Download the Data Loader.

Salesforce displays the Opening Apex Data Loader dialog:

3. Click Save File.

Salesforce downloads the Apex Data Loader.

4. Open the downloaded file ApexDataLoader.exe.

5. Follow the on-screen instructions to install the package on a client machine.

6. When installation has completed, click Close to exit the Setup dialog.



7. Open the Apex Data Loader, typically by clicking the desktop icon:

The first time you open the Apex Data Loader it displays a splash screen with a welcome message:

8. Click Cancel to display the standard Welcome screen:



9. Click Settings to display package default settings and check that the defaults are appropriate for your organization:

If you are unsure of the settings to use, start with the default settings and change them later if necessary.

10. When you are satisfied that the settings are as you want them, click OK.

The Apex Data Loader displays the standard Welcome screen.

You are now ready to use the Apex Data Loader.

Loading File Attachments in Bulk Generating a List of File Attachments


Generating a List of File Attachments

Your goal is to produce a CSV file which contains:

1. The Fairsail Team Member Employment Record Id

a. Use Fairsail to create a report to extract Team Member Name and Employment Record Id.

Include in the report any other fields you need to uniquely identify Team Members and to enable you to link each Team Member to the correct attachments.

The fields you choose will depend in part on the way the attachments have been named; ideally choose a field that is also used in the attachment file name. With a large number of attachments it is important that you can automate the process of linking Team Member to attachment.

b. Run the report and export the results to a CSV file.

2. The name of the file to be attached to the Employment Record.

Aim to generate a list of files complete with file extensions; this list can then be imported into the CSV file.

You can load more than one attachment for each Team Member through a single CSV file: add a new line for each attachment.

In the absence of dedicated utilities you can use MS-DOS through the Windows Command Prompt to generate a list of files from a Windows folder (MS_DOS directory) structure.

Use a command of the form:

dir [drive:] [path] *.* /s > [target filename]

For example:

dir C:\users\files\*.* /s > filelist.txt

...generates a list of all the files in the C:\users\files folder, including any files held in sub-folders, and writes the list to a text file called filelist.txt.

3. The path to the location where the file is stored.

This will be much easier if all file attachments are stored in the same folder.

4. The field names you are using in the file as the first line of the file.

Use field names that are meaningful to you; part of the data loading process is to map the field names to Salesforce fields so that the file can be correctly applied. .

You can use Excel to merge the contents of the CSV file generated from the report with the list of attachments. Use the Excel VLOOKUP function if necessary to help match Employment Record Id and attachments.

Loading File Attachments in Bulk Using the Apex Data Loader to Insert Attachments


Using the Apex Data Loader to Insert Attachments

1. Open the Apex Data Loader.

2. On the Welcome screen click Insert:

Apex Data Loader displays a login screen.

3. On the login screen enter your User Name and Password with Security Token.

Because you are accessing salesforce.com from desktop client software, you must append your security token to your password:

If your password is mypassword

and your security token is XXXXXXXXXX

enter mypasswordXXXXXXXXXX in the Password field

To get your security token:

Go to Setup > Personal Setup > My Personal Information > Reset My Security Token

Click Reset Security Token.

An email containing a new security token is sent to your registered email address.



4. Click Login.

Apex Data Loader displays the successful login screen:



5. Click Next.

Apex Data Loader displays the Select data objects screen:



6. Click Show all Salesforce objects:

7. Scroll down the list of objects and click Attachment:

8. Click Browse, find and select the CSV file that contains the list of attachments you want to add.

9. Click Next.

Apex Data Loader initializes the file and confirms the number of records it has found in the file:



10. Click OK.

Apex Data Loader displays a Mapping screen:



11. Click Create or Edit a Map.

Apex Data Loader displays a Mapping Dialog with Salesforce fields listed so that you can map them to the fields in your CSV file:

12. Drag and drop the Salesforce fields from the top panel onto your fields in the bottom panel to set up the following mapping:

Your CSV file column Salesforce field name

Employment Record ID ParentId The identifier that links an attachment to a Fairsail Team Member.

File Name Name The name of the attachment file.

Path Body The path to the attachment file location.

13. Click Save Mapping to save a copy of the mapping for future use.



14. Click OK.

Apex Data Loader displays the Mapping screen with your newly defined mapping added:



15. Click Next.

Apex Data Loader displays the Finish screen:

16. Click Browse..., find and select the folder for your success and error files.



17. Click Finish.

Apex Data Loader asks you to confirm that you want to insert new records:

18. Click Yes.

Apex Data Loader works through your CSV file, loading the attachments it can successfully locate and attach to an Employment Record. Apex Data Loader displays progress information followed by an Operation Finished dialog with buttons to View Successes and View Errors:

Successful loading adds an attachment to a Team Member's Employment Record for each line in the CSV file.

19. Click View Successes to display the insert log file listing attachments successfully applied.

Click View Errors to display the error log.

Click OK to close the dialog and return to the Welcome screen.

20. Open Fairsail HCM and check a sample of your Team Members to make sure that the attachments have been correctly applied to their Employment Record Notes & Attachments related lists.


Glossary of Terms

API Name

A unique reference name for a field in a Fairsail object. Every field has an API (Application Programming Interface) Name that is used internally by the software to ensure exact field matching. Unlike the field label, an API field name cannot change.

An example API Name for an HCM field with the label Unique Id is fHCM2__Unique_Id__c

Current data

Data field values representing the present state for a Team Member. Many current data records also have earlier versions that carry history data for the Team Member, such as salary history and job history.

Fairsail Data Loader

A separately supplied add-in package, designed to simplify and automate the process of loading bulk current and history data into Fairsail. Fairsail Data Loader includes Fairsail Template Generator for creating template files for data loading.

Fairsail Template Generator

Part of the Fairsail Data Loader add-in, enabling you to create template files in the correct format for loading data into Fairsail.

Field label

A text name for a field. Field labels are used on the user interface and in most cases can be changed as part of a localization project, or to conform to an organization's internal or industry specific terminology. Field labels map on to underlying API Names, which cannot be changed.

HCM

Human Capital Management. Fairsail HCM includes Fairsail WX or the Collaboration Portal for the end user, Team Member audience, and the HR Manager Portal for the HR Administrator.

History data

Data field values that are earlier than current values. For example, a Team Member has a current salary, and over time as a result of salary awards will build a history of previous salary values. All values that predate the current salary are part of the Team member's salary history data.

HRIS

Human Resource Information System. That part of the Fairsail HCM application that is maintained by HR to support team members.

Object

A container used by Fairsail for storing information of a particular type, such as Team Member, Employment Record, Salary, or Absence. Each object is stored as a table, with columns for fields and rows for records. For example, each Team Member record (Steve Pendleton, Linda Haliwell, Guy Smiley) forms a row in the Team Member object with fields for name, job title, location, manager, and so on. Objects can be linked to other objects, so building a composite set of information about the people in your organization.

Package

A container for SFDC applications and components, from which they are installed.

Glossary


UTF-8

UCS (Universal Character Set) Transformation Format-8 bit. A standardized format for character encoding that can represent every character in the Unicode character set. UTF-8 is the required character format for the Fairsail Data Loader.


Index

A Additional Guidelines • 8 Alternative file formats • 7 API Name • 54

C Creating a Template for Current Data • 11, 20 Creating a Template for Single Data Objects • 14,

24 Current data • 11, 20, 54

D Delimiters • 7, 8 Displaying Information About Data Loads • 23,

28, 32

E Excel as CSV source • 8

F Fairsail Data Loader • 54 Fairsail Template Generator • 54 Field label • 54 Field separator • 7 File format • 7

G Generating a List of File Attachments • 40, 44

H HCM • 54 History data • 14, 24, 54 HRIS • 54

I Input file specification • 7, 11, 14, 20, 24 Installing the Apex Data Loader • 40, 41 Introduction • 4

L Loading File Attachments in Bulk • 40

M Mass Data Deletion • 29

O Object • 54 Object prefix • 8

P Package • 54 Pipe delimiter • 7

S Starting a New Data Load From the Data Loads

Tab • 32, 35 Starting Fairsail Data Loader • 9

T Tab delimiter • 7 Template generation • 9, 11, 14

U Unicode • 7 Upgrading an Existing Data Loader Package • 6 Uploading Current Data • 20, 35 Uploading History Data • 24, 35 Using Picklist Exporter • 17 Using the Apex Data Loader to Insert

Attachments • 40, 45 Using the Data Load Detail Page • 32, 34, 36 Using the Data Loads Tab • 33 Using the Fairsail Data Loader • 9 UTF-8 • 7, 8, 55

Documents

Fairsail Data Loader Implementer's Guide - Sage Peoplehelp.sagepeople.com/Fairsail Data Loader Implementer's... · · 2016-08-25Competency Competency Assessment Competency Library