Signify Payroll Connector for Sage

This document describes the integration process between Signify (V10) and SAGE 300 People with a specific focus on the API integration.

General business rules:

1. In this case, SAGE is the source of the basic employee information.
2. The integration job will be executed on the Signify V10 system and is usually scheduled to run during the night.
3. Signify calls the SAGE APIs to obtain a bulk dataset with multiple fields and all employee records.
4. If the expected record count of the dataset is expected to exceed 5,000, please liaise with a technical Signify consultant.
5. Some of the fields in the dataset may be empty due to the fields not being populated in SAGE:
   a. In such cases:
         i.These fields can be maintained on the Signify system
         ii. Left blank, as the client may not require it
   b. If preferred, the client may choose to purchase additional modules in SAGE to maintain such fields in SAGE. It is, however, not a requirement as such fields can be maintained in Signify.
   c. Example: If OFO codes are required, the Skills module in SAGE is required, alternatively, these values can be maintained on the job profile in Signify.

Process business rules:

The integration process architecture is depicted in the image below:

1. The integration process that is executed by the Signify system calls an API on the SAGE server to retrieve a dataset with all the employee records from SAGE.
2. This dataset includes active employee records, as well as employee records for employees who were terminated during the previous [TBD] months.
3. Optional: An option to provide a parameter to only return records that were changed in the last [X] days will help to limit the size of data to be pulled during the API request. This option must, however, allow for all records to be pulled.
4. This dataset is stored in a staging table in the Signify system, from which the data transformation is done:

• Employee number is used as the unique identifier and is used in the [EmployeeCode] and [Username] fields in Signify, where [Username] must be unique.
• If an employee number does not exist in Signify (in the [Username] field), a new record is created in Signify.
• If an employee number exists, the existing record is updated in Signify.
• If Job and Position codes are available from SAGE:
  • If a job code and position code do not exist in Signify, a new job profile and linked position title are created in Signify.
• If Job and Position codes are NOT available from SAGE:
  • If a job title and position title do not exist in Signify, a new job profile and linked position title are created in Signify.
  • This may cause unused job profiles to remain in Signify and may have to be cleaned up manually.
• If Organisation unit codes are available in SAGE:
• If an organisation unit does not exist in Signify, a new organisation unit is created in Signify.
• The above means that all new appointments, terminations, and movements are made.

For additional information regarding the SAGE 300 People APIs:

http://documenter.getpostman.com/view/7078460/UVRBn6LC#db6e0efe-8d5d-4e1b-b0e7-c6de98410295

Who to involve:

1. A Signify technical consultant will ensure that the above process is implemented from a Signify point of view.
2. A SAGE technical consultant (usually a SAGE channel partner) must configure the API on the SAGE hosting environment.
3. SAGE clients can choose if the way to use their channel partners to configure the necessary API process.
4. Alternatively, Signify can connect the client or their channel partner with a SAGE technical consultant that Signify has partnered with on previous projects, and who can implement the process within a time effort of between 2 and 6 hours.
5. The consultant will deploy a custom SQL script on the SAGE database.
6. An SSL certificate must be purchased by the client and configured by the SAGE consultant.
7. The SQL script is executed when the Generic SAGE API is called.
8. The API is: http://{{HostName}}:{{APIPort}}/api/apibase/GenericGet/{{GenGetCodeAsSetupInPeople}}
9. Below is the list of fields that are required and recommended. Fields with no comments are optional. To ensure complete information, even fields with no comment should be added if available in SAGE:

Field Name

Field Signify Type

Description

Mandatory

Required/Optional/ ESS Configured Required / Recommended / Notes
(If blank, optional) EmployeeNumberexternalId UsernameInt YExternal Payroll Identity Id Optional Recommended: SAGE’s unique UserID for the employee IdNumberusername IdNumberstring AsUsername perto setupallow inthe Signifyuser to login Required Required – Usually the employee number GroupJoinDateemployeeCode StartDatestring YWhen empty it is set equal to username ESS Configured Required. Usually the employee number. If not provided, the username will be used. TerminationDatename EndDatestring AsName perof setupthe inuser SignifyESS Configured Recommended TerminationReasonsurname ReasonForTerminationstring IfSurname Terminatedof the user ESS Configured Recommended PassportNumberemailAddress PassportNumberstring AsEmail perfor setupmost notifications in Signifythe system e.g. Password reset ESS Configured Recommended as it can be used for communication and password resets EmployeeIdalternateEmailAddress ExternalIdstring AsEmail perfor setupreporting inESS SignifyConfigured
CellNumberidNumber MobileNumberstring AsId perNumber setupof inthe Signifyuser ESS Configured Recommended, but can be blank if required by client EmailpassportNumber EmailAddressstring AsPassport pernumber setupof inthe Signifyuser ESS Configured Recommended, but can be blank if required by client FirstNamemobileNumber Namestring YMobile number preferably with country code ESS Configured Recommended as it can be used for communication and password resets LastNameworkNumber Surnamestring YWork number preferably with country code ESS Configured
EmployeePositionIdhomeNumber JobExternalIdstring YHome number preferably with country code ESS Configured
OrganizationPositionmiddleName JobCodestring YMiddle name of user ESS Configured
OrganizationPositioninitials JobTitlestring YInitials of the user  ESS Configured Recommended EmployeePositionIdtitle PositionExternalIdstring YTitle of user ESS Configured Recommended OrganizationPositionknownAs PosCodestring YThe user is known as ESS Configured Recommended OrganizationPositionhomeLanguage PosTitlestring Y
ESS Configured
DirectlyReportsEmployeeNumbergender LineManagerUsernamestring N
ESS Configured
DirectlyReportsEmployeeNumberrace PerformanceManagerUsernamestring N
ESS Configured
PositionTypecitizenship AppointmentTypestring N
ESS Configured
UploadCode (OrganizationUnit)maritalStatus Org Code Level 1-9string Y
ESS Configured
Description (OrganizationUnit)birthDay Org Name Level 1-9string YDate of birth of the user ESS Configured
disability Org Id Level 1-9string YA single disability for the user ESS Configured
residentialUnitNumber string N
Optional
residentialComplexName string Y
Optional
MiddleNameresidentialStreetNumber string N
Optional
InitialsresidentialStreetName string N
Optional
TitleresidentialSuburbDistrict string N
Optional
PreferredNameresidentialCityTown string N
Optional
LanguageresidentialCountry string N
Required when any residential field supplied
GenderresidentialProvince string N
Required when any residential field supplied
RaceresidentialPostalCode string N
Optional
CitizenshipresidentialAsPostal string N
Optional
MaritalStatuspostalUnitNumber string N
Optional
WorkNumberpostalComplexName string N
Optional
HomeNumberpostalStreetNumber string N
Optional
BirthdaypostalStreetName string N
Optional
UnitNumberpostalSuburbDistrict string N
Optional
ComplexpostalCityTown string N
Optional
StreetNumberpostalCountry string N
Required when any postal field supplied
AddressLine1postalProvince string N
Required when any postal field is supplied
AddressLine2postalCode string N
Optional
AddressLine3jobExternalId int NThe payroll job ID Optional
AddressCountryjobTitle string ProvincejobCode string NCode of the job Optional
AddressCodeoccupationalCategory string NOccupation Category of the job Optional
SameAsPhysicaloccupationalLevel string NOccupational Level of the job within the category Optional
UnitNumberjobOfoCode string NOFO code of the job Optional
ComplexjobGrade PostalComplexNamestring NGrade of the job Optional
StreetNumbergradingType string NGrading used for the job Optional
AddressLine1positionExternalId int NThe payroll position Id Optional
AddressLine2positionTitle string NPosition Name Optional
AddressLine3positionCode string NPosition Code Optional
AddressCountryappointmentType string NHow the user is appointed in the position Optional
ProvincestartDate string NStart date in the position Optional
AddressCodeendDate string NEnd date in the position, when empty, the user is not terminated Optional
DisabledTypereasonForTermination string NThe reason the user's employment has ended Optional
GroupJoinDatestartDateInGroup string NThe start date in the group Optional
startDateInCompany string The start date in the company within the group Optional
orgLevel1_externalId Int Org unit Id on payroll Optional Recommended if available in SAGE orgLevel1_name string
Required Required – can be hardcoded if not available in source system orgLevel1_code string Unique code per ruleset for org unit Optional Required orgLevel1_workLocationName string
Optional Recommended if the client has this level in the org orgLevel2_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel2_name string
Optional Recommended if the client has this level in the org orgLevel2_code string Unique code per ruleset for org unit Optional Recommended if the client has this level in the org orgLevel2_workLocationName string
Optional
orgLevel3_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel3_name string
Optional Recommended if the client has this level in org orgLevel3_code string Unique code per ruleset for org unit Optional Recommended if client has this level in org orgLevel3_workLocationName string
Optional
orgLevel4_externalId Int Org unit Id on payroll Optional
orgLevel4_name string
Optional Recommended if client has this level in org orgLevel4_code string Unique code per ruleset for org unit Optional Recommended if client has this level in org orgLevel4_workLocationName string
Optional
orgLevel5_externalId Int Org unit Id on payroll Optional
orgLevel5_name string
Optional Recommended if the client has this level in the org orgLevel5_code string Unique code per ruleset for org unit Optional Recommended if the client has this level in the org orgLevel5_workLocationName string
Optional
orgLevel6_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel6_name string
Optional Recommended if client has this level in org orgLevel6_code string Unique code per ruleset for org unit Optional Recommended if client has this level in org orgLevel6_workLocationName string
Optional
orgLevel7_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel7_name string
Optional Recommended if the client has this level in the org orgLevel7_code string Unique code per ruleset for org unit Optional Recommended if the client has this level in the org orgLevel7_workLocationName string
Optional
orgLevel8_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel8_name string
Optional Recommended if the client has this level in the org orgLevel8_code string Unique code per ruleset for org unit Optional Recommended if the client has this level in the org orgLevel8_workLocationName string
Optional
orgLevel9_externalId Int Org unit Id on payroll Optional Recommended if the client has this level in the org orgLevel9_name string
Optional Recommended if the client has this level in the org orgLevel9_code string Unique code per ruleset for org unit Optional Recommended if the client has this level in the org orgLevel9_workLocationName string
Optional
lineManagerUsername string The username of the manager, existing in the system or part of the API body Optional
performanceManagerUsername string The username of the manager, existing in the system or part of the API body Optional
departmentManagerUsername string The username of the manager, existing in the system or part of the API body Optional
trainingManagerUsername string The username of the manager, existing in the system or part of the API body Optional
pdpFirstApproverUsername string The username of the manager, existing in the system or part of the API body Optional
pdpSecondApproverUsername string The username of the manager, existing in the system or part of the API body Optional
leaveManagerUsername string The username of the manager, existing in the system or part of the API body Optional
salaryReviewManagerUsername string The username of the manager, existing in the system or part of the API body Optional
talentManagementManagerUsername string The username of the manager, existing in the system or part of the API body Optional
secondaryReportingManagerUsername string The username of the manager, existing in the system or part of the API body Optional
lineManagerOnceRemovedUsername string The username of the manager, existing in the system or part of the API body Optional
workflowOriginatorUsername string The username of the manager, existing in the system or part of the API body Optional
financeManagerUsername string The username of the manager, existing in the system or part of the API body Optional
financeOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
hrOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
hrRecruitmentOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
businessUnitHrManagerUsername string The username of the manager, existing in the system or part of the API body Optional
secondaryJobRequisitionApproverUsername string The username of the manager, existing in the system or part of the API body Optional
leaveManagerAlternateApproverUsername string The username of the manager, existing in the system or part of the API body Optional