Product Update Release Notes Product:

Sage Employee Self Service

Version:

Product Update

Overview This document includes enhancements and modifications in Employee Self Service. Refer to the Sage Employee Self Service Installation and Setup Guide for upgrade instructions. Important! Employee Self Service should be installed by a certified Business Partner.

Support and Documentation Sage strives to provide you with the very best support in the industry. If you have a question, we provide the following methods for you to get your answer as soon as possible. •

Refer to the online Help for assistance. To access online Help, select Contents from Sage Employee Self Service Help menu and use the Table of Contents, Index, and Search function to find what you need. You can also click

to open Help for the function you are currently using.

•

Visit the Technical Forum and Solution Center on Abra SupportPlus Online at: http://www.sageabra.com/abraportal.html?RedirectKey=SUPPORT

•

Send an email (include your Customer ID) to: [email protected]

•

Call Sage Customer Support, Monday through Friday from 8:00 A.M. to 8:00 P.M. (ET) at 800-829-0170. Please have your Customer ID number available.

•

Visit SupportPlus Online and use Sage Live Chat, Monday through Friday from 9:00 A.M. to 5:00 P.M. (ET) at: http://kb.sagesoftwareonline.com/cgibin/sagesoftwareonline.cfg/php/enduser/chat.php?&_input_icf_43=135

Please have your Customer ID number available.

Table of Contents Product Update Release Notes .................................................................................... 1 Overview .............................................................................................................................................................. 1 Support and Documentation ............................................................................................................................. 1

Enhancements ............................................................................................................... 3 Employee Self Service ......................................................................................................................................... 3 New look and product branding for Sage Employee Self Service ........................................................ 3 Logon page .................................................................................................................................................... 4 FYI and Related Links section .................................................................................................................... 4 Menus ............................................................................................................................................................ 5 Page Alignment ............................................................................................................................................ 5 Icons and buttons ......................................................................................................................................... 6 Navigation..................................................................................................................................................... 6 ESS Home Page ............................................................................................................................................ 7 Other areas updated .................................................................................................................................... 9 Additional browsers supported ................................................................................................................. 9 Integrated Security/Active Directory ...................................................................................................... 10 Implementing Active Directory ............................................................................................................... 10 Logon Setup Changes ................................................................................................................................ 11 Sage Employee Self Service Mobility ...................................................................................................... 12 SSNs/SINs masked for dependents and beneficiaries........................................................................... 15 Time off requests ........................................................................................................................................ 15 Time Off Calendar...................................................................................................................................... 16 Publish Check Date .................................................................................................................................... 16 Sage Employee Analytics ................................................................................................................................. 16 Windows Logon and Employee Analytics ............................................................................................. 16 Using custom data in Sage Employee Analytics.................................................................................... 18 I-9 Fields in View Builder.......................................................................................................................... 18 Other ............................................................................................................................................................ 18 Benefits Open Enrollment ................................................................................................................................ 19 Changing Plans using Life Events ........................................................................................................... 19 Delete a Life Event ..................................................................................................................................... 19 Reason for Change in Sage HRMS updated from Employee Self Service .......................................... 19

Release Notes

1

Support and Documentation

Enrollment questions accessible during approval process .................................................................. 20 Current Benefits ......................................................................................................................................... 20 Approval option for Dependent or Beneficiary Changes .................................................................... 20 Open Enrollment ....................................................................................................................................... 20 Reports ........................................................................................................................................................ 21 Life Events .................................................................................................................................................. 21 Sage eRecruiter .................................................................................................................................................. 23

Modifications ............................................................................................................... 25 Employee Self Service ...................................................................................................................................... 25 Time Off Setup ........................................................................................................................................... 25 Benefits Open Enrollment................................................................................................................................ 25 Enrollment questions accessible during approval process .................................................................. 25 System ................................................................................................................................................................ 25 Registration Window ................................................................................................................................ 25 Server Error Handling............................................................................................................................... 25 Sage eRecruiter .................................................................................................................................................. 26

Appendix A - Custom Data ....................................................................................... 27 Exposing Custom Data in View Builder ........................................................................................................ 27 Toolkit Web Service/API........................................................................................................................... 28 XML Definition .......................................................................................................................................... 30 XML General Information section ........................................................................................................... 31 XML Data structure section ...................................................................................................................... 32 XML Data section....................................................................................................................................... 34 Sample Application ................................................................................................................................... 35 Real-time Custom Data Provider Interface ................................................................................................... 38 Implementing the Custom Data Provider .............................................................................................. 38

2

Sage Employee Self Service

Employee Self Service

Enhancements Employee Self Service New look and product branding for Sage Employee Self Service The product, originally named Abra Workforce Connections has been changed to Sage Employee Self Service. All applicable windows and text have been updated to reflect this change. Additionally, the look and feel of the product has significantly changed as follows. Note that the following changes also apply to Sage eRecruiter. There are now eight cascading stylesheets available for system customization. The original four cascading style sheets originally shipped with product have been updated to the new look and feel of the product. Note: When you apply this upgrade, any stylesheets with these same file names in the …\Program files\Sage Software\Abra Workforce Connections\Web\Css folder will be overwritten. If you have edited the standard stylesheets for your application, make sure the file names are different from the following names before you upgrade. •

AbraDefaultBlue.css

•

AbraDefaulBlueLogin.css

•

AbraDefaultGreen.css

•

AbraDefaultGreenLogin.css

•

AbraDefaultRed.css

•

AbraDefaultRedLogin.css

•

AbraDefaultPurple.css

•

AbraDefaultPurpleLogin.css

To change the stylesheet and the look of the: •

Logon page, select System Administrator > Styles and Graphics > Customize Logon Page.

•

Pages for a company, select System Administrator > Styles and Graphics > Customize Employer.

Release Notes

3

Employee Self Service

Logon page Logon page (before any customization) displays as the following. The two links Forgot Your Password? and First Time User Register Here have been added as well as a more simplified appearance.

•

Create New User is now First Time User Register Here

•

Change or Reset Password is now Forgot Your Password?

FYI and Related Links section The FYI and Related Links areas have been reformatted and updated. •

FYI and Related Links are now separate areas that can be expanded or collapsed as needed:

Collapsed

Expanded

4

Sage Employee Self Service

Employee Self Service

•

The field Display FYI and Related Links section (with Yes/No indicators) has been added to the Create Custom Menu page to enable the system administrator to choose whether or not to display the FYI and Related Links sections.

Menus Menus easily expand and collapse by clicking the menu header.

Note: The Career Center link has been moved under the Employee section.

Page Alignment Employee Self Service now opens in the center of the browser (no longer aligned on the left).

Release Notes

5

Employee Self Service

Icons and buttons •

The following icons have been updated to a more modern look: New Edit Delete Print Preview Refresh Popup calendar

•

Buttons that appear in the command bar at the top of pages have been updated to a more modern look and feel. They have also been repositioned and aligned to the right side of the bar. For example:

Navigation The navigation has been updated. •

The Message Center has been removed from the Navigation Pane on the left and replaced link in the upper right hand corner of the page. You can access this link with from any page in Employee Self Service.

• A new menu item, Reports, has been added to the Navigation Pane. This menu item goes to the Report Library, which contains the reports such as Crystal reports that have been loaded to the server for Employee Self Service.

6

Sage Employee Self Service

Employee Self Service

ESS Home Page A new Home page is now available. To define whether the Home page appears or the Message Center appears when you log on to ESS, in System Administrator > System Settings > System Setup, select Yes or No for Display Home Page. To return to your Home page at any time, click the upper right hand corner of the page.

in

The Home page displays ESS gadgets. To define the gadgets you view on your Home page, click the Personalize link on the Home page. Select the Visible check box for one or all of the following gadgets to appear: •

Current Benefits

•

Pay History

•

Recent Messages

•

Time Off Summary

After you select the gadgets to view, you can drag and drop the gadget on your Home page to the location you want. Click the More>> link on the gadget to navigate to that page. For example, if you click More>> on the Current Benefits gadget, you will go to the Current Benefits page.

Release Notes

7

Employee Self Service

In System Setup, select Yes for the Display Home Page view or No to display the Message Center as the page that appears when you log on to ESS..

To define which ESS gadgets appear on your Home Page, click the Personalize.

The Personalize page appears and you can select one or more items to appear on your Home Page.

8

Sage Employee Self Service

Employee Self Service

Other areas updated •

The Help button displayed at the top of each page has been replaced with an expandable Help menu. Click the arrow to expand the menu and select Help for the page or select About for Employee Self Service system information:

•

All required fields are now indicated with a black asterisk, for example:

If the page is saved without the required information, a message displays at the top of the page and the asterisk changes to red. •

The Welcome [User Name] field and Log off link at the top of the page have been combined into one link that displays the log off command, followed by the user name:

Additional browsers supported All Sage Employee Self Service pages are now compatible with the following browsers. •

Microsoft Internet Explorer v8.0.6001

•

Microsoft Internet Explorer v9.0

•

Mozilla Firefox v3.6.13

•

Google Chrome v8.0.552

•

Apple Safari v3.2.3

Note: Master Logon pages for View Builder Roles, System Setup, and Time Off Setup are also compatible with the browsers above. However, Create Custom Menu and Customize Logon Page are not.

Release Notes

9

Employee Self Service

Integrated Security/Active Directory An Employee Self Service user can now log on either with an Employee Self Service user name and password, or with their Windows user account login.

Implementing Active Directory System Maintenance Changes To accommodate the new Windows authentication login, the Login Authentication Method setting has been added to the System Maintenance page. •

If you select Active Directory, the domain name, user name, and password are required.

In this case, when the user opens the home page, they must enter their Windows user account information, with their domain, to log on.

If this is their first time logging on, they are requested to enter their logon information (such as first name, last name) so the system will recognize them as that user when they log on. There is no requirement to answer a security question when the user logs on with their Windows user account. •

10

If you do not select Active Directory, the domain name, user name, and password are not required.

Sage Employee Self Service

Employee Self Service

Then when the user opens the home page, they must enter their Employee Self Service logon (created when they first logged on to the system). If this is their first time logging on, they must click First Time User Register Here to establish their user name and password, and to answer their security question.

Logon Setup Changes In the Logon Setup, new fields were added to the Self Service Password Properties section. Use these fields to set the criteria for user passwords.

Release Notes

11

Employee Self Service

Note: If you selected Active Directory in System Maintenance, you will not see the System Questions section on this page and the Self Service Password Properties apply only to the Master user.

Multiple Companies, One Logon You now have the ability to log on to multiple companies using your Windows logon. If your logon is associated with multiple companies, after you log on to the Employee Self Service, a new window appears on which you select the company you want to access for that session.

Sage Employee Self Service Mobility To allow employees and managers flexibility in how they interact with each other and provide an anytime, anywhere, instant connection to Employer Solutions applications, we have added Sage ESS Mobility. ESS Mobility will improve productivity by making it easier for managers and employees to complete a wide range of employee management related tasks using a variety of mobile devices. For employees this means easy access to critical aspects of their working life from the mobile devices they already use and with which they are familiar. ESS Mobility currently supports the following devices:

12

•

iPhone (3G, 3GS, 4G)

•

iPod

•

Android

•

Blackberry

•

Windows CE

Sage Employee Self Service

Employee Self Service

•

Windows Phone 7

•

Windows Mobile

ESS Mobility will provide the following functionality to employees with access to ESS. •

Notify the employee of payment history

•

View payment history

•

View time off balances

•

Request Time off

•

View Time off approval

•

Manage Time off requests

Employee Messages - When new information is available to an employee, ESS Mobility will indicate the new information such as: •

New requests for time off

•

New time off approvals

•

New messages

Pay History - The employee can view his or her current and past pay stubs. Most recent paychecks including the pay date, hours worked, and net pay will display. If you click on the individual check, you can view the detail for a selected check stub or advice. Time Off - This redirects the employee to the page where they can enter their request. Current Benefits – This displays a summary of your benefits by plan.

Manager ESS Mobility recognizes managers (those employees with employees reporting to them) and includes added functionality, such as access to their direct reports as well as indirect reports defined in ESS: In addition to the functionality of the employee, the manager has the following options are available for viewing:

Release Notes

13

Employee Self Service

Messages - When information is emailed to managers, you will have the ability to access the specific information from the email link. •

View time off requests from the employee.

•

From the request, the manager can approve or reject the time off request. They will also have the ability to enter comments on the approval or rejection.

•

Emergency Contact List - View a list of emergency contacts for each employee.

How do I use ESS Mobility? To connect to ESS Mobility, you must have access to Sage Employee Self Service. 1.

Open a Browser session.

2.

Enter the URL for your Employee Self Service to access the application.

3.

After you are connected, enter your User Name and Password.

Note: The pages available in ESS Mobility are dependent on your security settings in Employee Self Service.

14

Sage Employee Self Service

Employee Self Service

SSNs/SINs masked for dependents and beneficiaries To increase system security, dependents’ and beneficiaries’ social security (and social insurance) numbers are now masked in windows and on reports, so that only the last four digits of the number are displayed. Details are as follows: •

A new system setting is provided to enable/disable this masking. The setting applies to all employers in the system and is located on the System Setup window.

•

The SSN/SIN display on the employee’s Personal Profile page remains the same. The employee can click the Show Number link to display the entire number.

•

Masking does not apply when in add or edit mode so that the user can see the entire SSN/SIN number when adding or editing.

•

Specific pages that have been updated are: −

Employee > Personal > Dependents and Beneficiaries summary page

−

Employee > Open Enrollment > Summary tab

−

Employee > Open Enrollment > Benefits tab

−

Employee > Open Enrollment > Summary tab > Print summary report

−

Employee > Payroll > Pay History> Preview

−

Applicants > Management > Personal

Time off requests When managers receive time off requests in Employee Self Service, the time of day that the request was made is now included in the notification message. This information can help the manager to make staffing decisions while approving requests.

Release Notes

15

Sage Employee Analytics

Time Off Calendar New functionality, Time Off Calendar, has been added to the manager role for Employee Self Service. This feature displays a monthly view calendar, which allows the manager to see the details of time off requests for his or her employees. On this calendar, you can: •

Navigate to other months using the Previous and Next arrows

•

Easily identify the current date

•

View the details of requests at a status of: −

Approved

−

Pending

−

Rejected

Publish Check Date The employee’s check now appears in the Pay History on Employee Self Service based on the date defined in Sage Payroll. The default date the check appears is the same as the check date but you can change it during the Print Check process or the Update Publish Check Date process in Sage Payroll. The date you enter as the publish date appears in Employee Self Service on the employee’s Pay History Report.

Sage Employee Analytics Windows Logon and Employee Analytics New functionality has been added to allow users to access employee analytics using their Windows log on authentication. Now, when you log on with your Windows logon, you can access employee analytics in the: •

Launching the View Builder from ESS

•

Opening a new tab and entering the URL while in an ESS session

•

Selecting a Custom page from within ESS

If you open a new browser session and enter the URL, you must have Lightweight Directory Access Protocol (LDAP) and Secure Sockets Layer (SSL) configured for your system or you cannot access the View. The following View Builder functionality is available using the Windows logon.

16

Sage Employee Self Service

Sage Employee Analytics

•

When Windows Logon and SSL are configured for your system, all employees must create an ESS account using their Windows account credentials (see page 10) before they can access any Views.

•

All employees accessing a View using a URL are presented with a Logon page requesting the User Name and Password. However, if SSL is not configured and Windows authentication is, the user is unable to access a View and will receive a message.

•

If an employee is associated with more than one company: −

The Select a Company page appears when creating an ESS logon using his or her Windows account. After the logon is created, a record is created, in the ESS database, for each company with which the employee is associated. Note: When accessing a View, the employee must use the same Windows Account logon information for all company records.

−

A Company Code field appears at the top of the View when accessing it by entering an URL. The value in the Company Code field defaults to the first company in alphabetical order. The dropdown list will include all companies with which the employee is associated in ESS.

•

If the employee switches either the company or the View format (Table versus Individual records), the Company Code field remains on the page.

•

If the employee has a different role in the second company, which is not assigned to the View, a message, "You are not authorized to view this information." displays to the user when the Company Code field is changed.

•

When a View is added as a Custom page in ESS and an employee associated with more than one company is logged on to ESS and the Custom page is:

•

−

Set to launch within the ESS frame, the Company Code field is not displayed

−

Set to launch a new Browser window, the Company Code field is not displayed

The Company Code field will never display if the employee is in the same browser session

Release Notes

17

Sage Employee Analytics

Using custom data in Sage Employee Analytics Views can now include custom data from Toolkit, external data sources, third-party applications, and through implementation of a Custom Data Provider interface. This includes: •

Manually entered fields on Sage HRMS custom details (single or multi-record) are automatically available for views

•

A Data Sync Web Service is available to enable external data source and third party applications to be integrated with toolkit data in Sage HRMS via an XML file

•

A Custom Data Provider Interface is available to integrate directly into the View Builder, real-time, to retrieve and expose data available for views

Refer to Appendix A for a separate document with a detailed explanation and instructions.

I-9 Fields in View Builder The following fields to capture I-9 documents have been added to View Builder and are available in Personnel: •

Work Authorization

•

Document A

•

Document A - Date Expiration

•

Document B

•

Document B - Date Expiration

•

Document C

•

Document C - Date Expiration

Note: These fields are entered on the HR Status window in HRMS.

Other A new check box, Current Date, has been added to the Set Filter tab of View Builder. Select this check box to create expressions using the current date.

18

Sage Employee Self Service

Benefits Open Enrollment

Benefits Open Enrollment Changing Plans using Life Events Issue: When changing from one medical plan to another during a life event, the system left both the original benefit and deduction and the new benefit and deduction active. Resolution: This has been corrected so that when a life event is changed from one plan to another, the following rules apply: •

When plans are changed, the old linked deduction is stopped as of the life event effective date, and the new linked deduction is added for the new plan as of the life event effective date.

•

When a plan is waived, the deduction is stopped as of the life event effective date.

•

When changing a new election is for the same plan as the previous plan (usually when the elected plan is the same, but only the options have changed), the linked deduction is not stopped, but remains effective as of the original effective date.

•

When electing a new plan, the linked deduction code is added as of the life event effective date.

Delete a Life Event Previously, if an employee began the process of entering a life event, for example, the birth of a child, they were unable to delete the life event if they began the process by mistake. This has been corrected. A new Delete button has been added. If the Life Event process status is Pending or In Progress, the employee can now click the Delete button to delete the Life Event.

Reason for Change in Sage HRMS updated from Employee Self Service The Reason for Change field in Sage HRMS (on the employee’s Insurance > Savings Benefits Detail) now displays the specific description of the Life Event or Open Enrollment period that caused the change to the plan in Sage HRMS. For example, a life event of Marital Status Change or the open enrollment period called Open Enrollment Spring 2010. Previously, all reasons that originated from Employee Self Service displayed as Update Benefits in the Reason for Change field.

Release Notes

19

Benefits Open Enrollment

Enrollment questions accessible during approval process Required enrollment questions answered by the employee while enrolling in a benefit plan either through open enrollment or a life event, can now be displayed during the enrollment approval process. A new Questions hyperlink has been added to the employee’s benefit record that, when clicked, opens a separate page showing the questions and answers.

Current Benefits Previously, the employer contribution on the Current Benefits page would appear as a rounded value and not the actual value. This has been corrected and now the actual value appears.

Approval option for Dependent or Beneficiary Changes The ability to approve dependent and beneficiary changes in ESS has been added to the Employer Setup page. Now you can define access as No Access, View, Update, Notify, or Approve.

Open Enrollment •

The following changes were made to the Open Enrollment (OE) process: 1. If the OE status is Incomplete the text is red; if the status is otherwise, the text is blue. The status appears in red so that you can easily identify that you need to complete your open enrollment selections and submit them. 2. The Done button was removed from the top of the OE Exit wizard and is now located under the SSN control. 3. The Exit button has been removed from OE Exit wizard.

20

•

Previously, the employee would make their benefit elections and submit them but never get a notification that the Open Enrollment selections or the Life Event was successfully submitted. Now, the employee will receive a notification to indicate the OE or LE elections were successfully submitted.

•

Previously, the hyperlinks to the plan pages on the Open Enrollment Exit page did not appear in color so it was difficult to see if you had clicked the link or not. This has been updated so the hyperlinks are now blue if the link has not been clicked and maroon if they have been clicked.

Sage Employee Self Service

Benefits Open Enrollment

Reports A new report, Provider Enrollment, has been added to the Benefit reports (System Administrator > Benefit Reports.) Use this report to view the details of one or all employees during the open enrollment period. You can view the details for employees in one or all companies and one or all benefit plans. You can use this report to send information to the benefit provider prior to sending the records to Sage HRMS.

You can select any of the following to include on this report: •

Enrollment Period – available enrollment periods defined

•

Employer – employers

•

Benefit Plan – a single benefit plan or all benefit plans

•

Search – enrollment status or employee last name

Note: If you select an option in the Search field, another field appears in which you can further define the search. For example, if you select Enrollment Status, another field appears for you to select the status. After you define the search criteria, click Go. This report is available for preview, print, and export. Click Preview to view and print the report or click Export to export the report to an Excel spreadsheet.

Life Events The Life Events functionality has been updated to allow newly hired employees to view or select benefit plans. A new Event Type, New Hire, was added to the Benefit Setup > Life Events page. After you select New Hire, the Benefits Effective Date fields appear.

Release Notes

21

Benefits Open Enrollment

•

•

•

Source Date, select from −

Original Hire Date

−

Last Hire Date

−

Adjusted Seniority Date

Units, select from −

Days

−

Months

−

Full Months

−

Quarters

−

Full Quarters

−

Years

−

Full Years

Number of Units Enter the number of units. You can enter up to three characters.

22

Sage Employee Self Service

Sage eRecruiter

•

Effective On, select from −

Exact Date

−

First Day of the Month Following

−

First Day of the Quarter Following

−

First Day of the Year Following

On the Summary page, the Event Type will appear as New Hire. If an event with the New Hire event type is selected, the Event Date field is disabled and the date is calculated based on Benefit Effective Date fields entered on Life Events page.

Sage eRecruiter •

The Help button at the top of the page has been replaced with an expandable Help menu. Click the arrow to expand the menu and select Help for the page or select About for system information:

•

The Career Center link has been moved under the Employee menu in Employee Self Service.

Release Notes

23

Modifications Employee Self Service Time Off Setup A new system setting, Allow Past Time Off Requests, has been added to the Time Off Setup page (System Settings > Time Off Setup). If you set this to Yes, employees can submit time off requests for past dates. If it is set to No, employees are unable to submit requests for past dates.

Benefits Open Enrollment Enrollment questions accessible during approval process Required enrollment questions answered by the employee while enrolling in a benefit plan either through open enrollment or a life event, can now be displayed during the enrollment approval process. A new Questions hyperlink has been added to the employee’s benefit record that, when clicked, opens a separate page showing the questions and answers.

System Registration Window Submitting registration and contact information is no longer required. Therefore, the Registration window has been removed from the system and is no longer displayed upon logon.

Server Error Handling Previously, you could not access and view the SQL Error log files (xme) on the Server Errors tab in Employee Self Service System Maintenance. Now, after you select a SQL error on the Server Errors tab, you can view a description of the error. You can also select any of the following items for additional information on the error: •

Environment

•

Message

•

Source

Release Notes

25

Sage eRecruiter

•

Stacktrace

•

Targetsite

Sage eRecruiter The same facelift changes made for Employee Self Service also apply to Sage eRecruiter. To review these changes, see the “New look and product branding for Sage Employee Self Service” section on page 3.

26

Sage Employee Self Service

Appendix A - Custom Data Exposing Custom Data in View Builder View Builder, delivered with Sage Employee Self Service (ESS), provides the ability to deliver Sage Employee Analytics to Executives, Managers, and Employees. With the upcoming SQL release we have extended View Builder to view custom data created through Toolkit in Sage HRMS. Any custom fields that are created in Toolkit are automatically exposed in View Builder. The figure below is an example of toolkit data exposed in View Builder. All toolkit data is available under a node called Custom.

Custom data created in Toolkit can be accessed and used in View Builder in the same way as the current View Builder data is available. It can be used to select, view, filter, sort, etc. The next figures show an example of Toolkit data rendered in View Builder.

Release Notes

27

Exposing Custom Data in View Builder

Toolkit Web Service/API Another feature that has been added to Employee Self Service is the ability to populate toolkit data by using a web service. This enables any external data source/third party application data to be integrated with toolkit data in Sage HRMS. The web service is located in the ESS web path http:///scripts/datasync.asmx.

The datasync.asmx web service is made up of one supported operation: Sync. The Sync operation has three parameters:

28

•

strXml: This parameter is the xml string which contains the toolkit data and data structure. The xml format will be discussed later in the document.

•

user and pwd: The user name and password for data sync purposes is set on the ESS System Setup page (System Administrator > System Settings > System Setup):

Sage Employee Self Service

Exposing Custom Data in View Builder

The top of the following figure shows the area on the DataSync window where these parameters are entered.

Release Notes

29

Exposing Custom Data in View Builder

XML Definition As stated above, the Data Sync operation takes an xml string as the first input. The figure below is an example of a valid custom data xml string. The xml consists of three parts: General information, DataStructure, and Data, which will be discussed in more detail in the next sections. For the process to work, all parts must be sent in one xml file.

30

Sage Employee Self Service

Exposing Custom Data in View Builder

XML General Information section

1.

XMLSchemaVersion (Type=Number Length=10 Required=Y Valid Values=Number): To support multiple versions of xml that can be sent to the web service, the xml must pass a version. This is necessary so the web service knows how to process the payload. Version one allows for bulk data insert/replace. This version does not support CRUD (Create/Update/Delete). The current version of the web service always bulk replaces the custom data on subsequent calls.

2.

ExternalSourceId (Type=String Length=10 Required=Y Valid Values=Alpha numeric): This element is a unique identifier that identifies an external entity or third party application. For example, Aflac for an external entity or BP third party app name for a third party application. •

DataFeedId (Type=String Length=14 Required=Y Valid Values=Alpha numeric): An ExternalSourceId can have multiple data feeds. The DataFeedId element allows for multiple feeds to be sent to toolkit data in Abra HRMS. The combination of ExternalSourceId + “_” + DataFeedId uniquely identifies an external feed in Abra Toolkit. In the example at the top of this page, the key is Alfac_DuckBenefits. When a key is established and has been used by customers, you should not change it.

•

DataRelationship (Type=Number Length=1 Required=Y Valid Values=1,2): Abra toolkit has the ability to store data as a 1 to 1 relationship, which is stored in the table HRTKPERS. It also has the ability to store 1 to many relationships. In this case, each custom data feed generates a TKMULnnn table, where nnn is a sequential number assigned by the system. For 1 to 1 data feeds, the value for DataRelationship should be set to 1. For a 1 to many feed, the value for DataRelationship should be set to 2.

•

Description (Type=String Length=50 Required=Y Valid Values=Alpha numeric): The Description element is used to show the custom data feed in a user friendly manner in View Builder.

Release Notes

31

Exposing Custom Data in View Builder

XML Data structure section

32

Sage Employee Self Service

Exposing Custom Data in View Builder

The DataStructure section of the xml contains the Field properties, which are used to create the toolkit data structures. The fields are used to alter the HRTKPERS table or the assigned TKMULnnn table, depending on the DataRelationship passed in. 1.

Title (Type=String Length=20 Required=Y Valid Values=Alpha numeric): Each field must pass a title or description, which is used to display the column header.

2.

DatabaseField (Type=String Length=8 Required=Y Valid Values=Alpha numeric): The DatabaseField element is used to name each column in the database. Each value must be unique within the xml string. •

DataType (Type=String Length=1 Required=Y Valid Values=C,N,D,L): The field structure must pass the correct data type of the field. The valid values are described as: C = Character string (Abc123); any Ascii printable character N = Numeric (9999999.99999) D = Date (mm/dd/yyyy) L = Boolean (Y,N) Any values that are not valid generate an error report that is sent back to the external application.

•

Length (Type=Number Length=10 Required=Y Valid Values=Number): The maximum length of the field.

•

DecimalPlaces (Type=Number Length=10 Required=Y Valid Values=Number): The number of decimal places. This value is only relevant if the field is a number. Any other data type ignores this element.

•

Required (Type=String Length=1 Required=Y Valid Values=Y,N): The Required element determines if the value is required.

Release Notes

33

Exposing Custom Data in View Builder

XML Data section

The XML Data section contains DataRow elements. Each DataRow element contains child elements, which contain the data for each DataRow. Every DataRow element must have at a minimum two values: CompanyId and EmpNo. Without these elements, the data cannot be linked properly to Sage HRMS. Each name attribute on the value elements must match the DatabaseField name in the DataStructure section. If a named value does not match a DatabaseField name, that value is ignored and not processed. Important! All the data rows must be sent every time. This is because the process completely deletes the prior data and replaces it with the new data feed.

34

Sage Employee Self Service

Exposing Custom Data in View Builder

Sample Application A sample application, delivered with this release, calls the custom data web service. The sample application is located in a folder called DatasyncUI on the Desktop. The accompanying source code is located in a folder called DatasyncUISource on the Desktop. Note: This is a sample application and should not be used for production purposes. It is distributed for the sole purpose of understanding how to implement this feature.

1.

Point the URL to any location for the web service.

2.

Enter a User Id and Password. These must match the user name and password set in ESS for the Custom Data API User (on the System Setup > System Settings page).

3.

Browse to a valid xml file and click Execute to run the process.

4.

The Results control displays the result of the web service call.

Release Notes

35

Exposing Custom Data in View Builder

This sample application is a Windows-based application written in C# using Visual Studio 2010. The application code is shown below: private void btnExecute_Click(object sender, EventArgs e) { webBrowser.Document.Body.InnerHtml = string.Empty; webBrowser.Document.Write("Running"); XmlDocument xmlDoc = new XmlDocument(); xmlDoc.Load(lblFilePath.Text); DataSync dataSync = new DataSync(); dataSync.Url = tbURL.Text.Trim(); ReturnValues rv = dataSync.Sync(xmlDoc.OuterXml, tbUserId.Text, tbPassword.Text); string documentText = string.Empty; if (rv.ReturnCode == Result.Ok) { documentText = "Success!"; } else if (rv.ReturnCode == Result.FailedAuthorization) { documentText = "Authorization Failed!"; } else if (rv.ReturnCode == Result.FailedXSDInit) { documentText = "XSD Initialization Failed!"; } else if (rv.ReturnCode == Result.FailedXmlValidation) { XmlDocument resultInfo = new XmlDocument(); resultInfo.LoadXml(rv.ResultInfo); XmlElement rootElement = resultInfo.DocumentElement; XmlNodeList messages = rootElement.SelectNodes("//Error"); string message = "" + messages.Item(0).SelectSingleNode("ErrorDescription").SelectSingleNode("table").OuterXml + ""; documentText = message; } else if (rv.ReturnCode == Result.Exception) { XmlDocument resultInfo = new XmlDocument(); resultInfo.LoadXml(rv.ResultInfo); XmlElement rootElement = resultInfo.DocumentElement; XmlNodeList messages = rootElement.SelectNodes("//Error"); MessageBox.Show(messages.Item(0).SelectSingleNode("ErrorDescription").InnerText); } else { documentText = "Unkown Status!"; }

}

36

}

webBrowser.Document.Body.InnerHtml = string.Empty; webBrowser.Document.Write(documentText);

Sage Employee Self Service

Exposing Custom Data in View Builder

For flexibility, the test application’s result control is a web browser control. This is because the error report returned from the web service is in HTML format. In order to call the web service, a DataSync object has to be created. Then call the Sync method and pass in the xml and security information. DataSync dataSync = new DataSync(); dataSync.Url = tbURL.Text.Trim(); ReturnValues rv = dataSync.Sync(xmlDoc.OuterXml, tbUserId.Text, tbPassword.Text);

The call is synchronous. When it returns, process the ReturnCode as shown below. if (rv.ReturnCode == Result.Ok) { documentText = "Success!"; } else if (rv.ReturnCode == Result.FailedAuthorization) { documentText = "Authorization Failed!"; } else if (rv.ReturnCode == Result.FailedXSDInit) { documentText = "XSD Initialization Failed!"; } else if (rv.ReturnCode == Result.FailedXmlValidation) { XmlDocument resultInfo = new XmlDocument(); resultInfo.LoadXml(rv.ResultInfo); XmlElement rootElement = resultInfo.DocumentElement; XmlNodeList messages = rootElement.SelectNodes("//Error"); string message = "" + messages.Item(0).SelectSingleNode("ErrorDescription").SelectSingleNode("table").OuterXml + ""; documentText = message; } else if (rv.ReturnCode == Result.Exception) { XmlDocument resultInfo = new XmlDocument(); resultInfo.LoadXml(rv.ResultInfo); XmlElement rootElement = resultInfo.DocumentElement; XmlNodeList messages = rootElement.SelectNodes("//Error"); MessageBox.Show(messages.Item(0).SelectSingleNode("ErrorDescription").InnerText); } else { documentText = "Unkown Status!"; }

Release Notes

37

Real-time Custom Data Provider Interface

Real-time Custom Data Provider Interface If syncing third-party data with the AbraToolkit is not sufficient, it is possible to plug directly into the View Builder by implementing a specific .NET interface inside of a Class Library assembly and placing that library in the ESS Web\bin directory. When an ESS session is first initialized after the login, it scans this directory for custom data provider implementations and will display additional properties it finds inside of the View Builder below the Personnel\Custom grouping.

Implementing the Custom Data Provider •

The Custom Data Provider implementation can expose employee-level custom data on a oneto-one or a one-to-many basis in the same way as the Toolkit Provider.

•

The Custom Data Provider must be able to provide the metadata for all the custom properties of a given HRMS base entity (typically Personnel). This is what populates the View Builder tree. It also must be able to retrieve the property values for a specific employee when the view is rendered based on the primary key (Employee ID + Company Code).

•

How and from where the data is retrieved is left up to the consumer of the Custom Data Provider. Note that for large result sets, the provider is invoked for every row, so performance may be impacted if some caching mechanism is not considered in place of numerous database queries.

To implement a Custom Data Provider, a .NET assembly must reference the Abra.Data.Custom.dll already in the ESS Web\bin directory, and each provider class must implement the Abra.Data.Custom.IAbraCustomDataProvider interface. A sample provider is shown below to demonstrate how to model the two types of supported relationships to EmployeePersonnel and serve the data in View Builder. using using using using using

Abra.Data.Custom; System; System.Collections.Generic; System.Linq; System.Text;

namespace TestProvider { public class Provider : IAbraCustomDataProvider { private ICustomFieldMetaData _ShirtSize; private ICustomFieldMetaData _PerformanceReviewDate; private ICustomFieldMetaData _PerformanceReviewRating; private void InitMetaData(string className) { // Add a 1-to-1 property for T-Shirt Size _ShirtSize = new CustomFieldMetaData(this); _ShirtSize.BaseClass = className; _ShirtSize.CustomFieldDataType = typeof(string); _ShirtSize.CustomFieldName = "ShirtSize"; _ShirtSize.CustomFieldDisplayName = "T-Shirt Size";

38

Sage Employee Self Service

Real-time Custom Data Provider Interface

_ShirtSize.DisplayOrder = 1; // Add 2 one-to-many properties for Performance Reviews _PerformanceReviewDate = new CustomFieldMetaData(this); _PerformanceReviewDate.BaseClass = className; _PerformanceReviewDate.CustomFieldDataType = typeof(DateTime); _PerformanceReviewDate.CustomFieldName = "ReviewDate"; _PerformanceReviewDate.CustomFieldDisplayName = "Performance Review Date"; _PerformanceReviewDate.ParentEntityDisplayName = "Performance Reviews"; _PerformanceReviewDate.DisplayOrder = 2;

}

_PerformanceReviewRating = new CustomFieldMetaData(this); _PerformanceReviewRating.BaseClass = className; _PerformanceReviewRating.CustomFieldDataType = typeof(int); _PerformanceReviewRating.CustomFieldName = "ReviewRating"; _PerformanceReviewRating.CustomFieldDisplayName = "Performance Review Rating"; _PerformanceReviewRating.ParentEntityDisplayName = "Performance Reviews"; _PerformanceReviewRating.DisplayOrder = 3;

public string Name { get { return "MyProvider"; } } public string DisplayName { get { return "My Basic Provider"; } } public List GetMetaDataForClass(string className) { List metaData = new List(); if (className == "Abra.Ste.BusinessObjects.EmployeePersonnel") { InitMetaData(className);

} }

metaData.Add(_ShirtSize); metaData.Add(_PerformanceReviewDate); metaData.Add(_PerformanceReviewRating);

return metaData;

public CustomFieldDataCollection GetCustomData(string className, string pk) { CustomFieldDataCollection results = new CustomFieldDataCollection(this); if (className == "Abra.Ste.BusinessObjects.EmployeePersonnel" && pk == "101 "Donald Adams" in Abra Sample Data { InitMetaData(className); // First add one-to-one property results.EmployeeLevelData = new List(); ICustomFieldData shirtSizeData = new CustomFieldData(); shirtSizeData.MetaData = _ShirtSize; shirtSizeData.DataValue = "XL"; results.EmployeeLevelData.Add(shirtSizeData);

ZSI") //

// Add Multi-row data results.MultiRowData = new List(); IMultiRowCustomData performanceReviewMultiData = new MultiRowCustomData();

Release Notes

39

Real-time Custom Data Provider Interface

results.MultiRowData.Add(performanceReviewMultiData); performanceReviewMultiData.GroupName = _PerformanceReviewDate.ParentEntity; performanceReviewMultiData.CustomData = new List(); // Now add the individual multi-row records, starting with the first performance

review

List row1PerformanceReviewData = new List(); performanceReviewMultiData.CustomData.Add(row1PerformanceReviewData); ICustomFieldData row1ReviewRating = new CustomFieldData(); row1ReviewRating.MetaData = _PerformanceReviewRating; row1ReviewRating.DataValue = 4; row1PerformanceReviewData.Add(row1ReviewRating); ICustomFieldData row1ReviewDate = new CustomFieldData(); row1ReviewDate.MetaData = _PerformanceReviewDate; row1ReviewDate.DataValue = new DateTime(2010, 2, 1); row1PerformanceReviewData.Add(row1ReviewDate); // Add the 2nd performance review List row2PerformanceReviewData = new List(); performanceReviewMultiData.CustomData.Add(row2PerformanceReviewData); ICustomFieldData row2ReviewRating = new CustomFieldData(); row2ReviewRating.MetaData = _PerformanceReviewRating; row2ReviewRating.DataValue = 5; row2PerformanceReviewData.Add(row2ReviewRating); ICustomFieldData row2ReviewDate = new CustomFieldData(); row2ReviewDate.MetaData = _PerformanceReviewDate; row2ReviewDate.DataValue = new DateTime(2010, 3, 1); row2PerformanceReviewData.Add(row2ReviewDate); } }

return results;

public bool WriteCustomData(string className, string pk, CustomFieldDataCollection customData) { // Not currently implemented

}

40

}

}

return true;

Sage Employee Self Service

Real-time Custom Data Provider Interface

If the above code is compiled into an assembly and placed into the ESS Web\bin directory, the three additional custom properties (shirt size, performance review date, and performance review rating) will now be available inside of the View Builder grouped by the provider’s DisplayName property as shown below:

Selecting the three properties (along with the built-in properties for First Name and Last Name) will cause them to render in a similar manner as existing one-to-one and one-to-many properties as shown in the following figure.

Release Notes

41