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:

Mandatory

Signify in

Field Name	Field Signify Type	Description	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	ESS 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	ESS 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
OrganizationUnitId (OrganizationUnit) disability	Org Id Level 1-9string	YA single disability for the user	ESS Configured
PassportNumber residentialUnitNumber	PassportNumber string	N	Optional
EmployeeId residentialComplexName	PayrollId string	Y	Optional
MiddleNameresidentialStreetNumber	MiddleName string	N	Optional
InitialsresidentialStreetName	Initials string	N	Optional
TitleresidentialSuburbDistrict	Title string	N	Optional
PreferredNameresidentialCityTown	KnownAs string	N	Optional
LanguageresidentialCountry	HomeLanguage string	N	Required when any residential field supplied
GenderresidentialProvince	Gender string	N	Required when any residential field supplied
RaceresidentialPostalCode	Race string	N	Optional
CitizenshipresidentialAsPostal	Citizenship string	N	Optional
MaritalStatuspostalUnitNumber	MaritalStatus string	N	Optional
WorkNumberpostalComplexName	WorkNumber string	N	Optional
HomeNumberpostalStreetNumber	HomeNumber string	N	Optional
BirthdaypostalStreetName	BirthDay string	N	Optional
UnitNumberpostalSuburbDistrict	ResidentialUnitNumber string	N	Optional
ComplexpostalCityTown	ResidentialComplexName string	N	Optional
StreetNumberpostalCountry	ResidentialStreetNumber string	N	Required when any postal field supplied
AddressLine1postalProvince	ResidentialStreetName string	N	Required when any postal field is supplied
AddressLine2postalCode	ResidentialSuburbDistrict string	N	Optional
AddressLine3jobExternalId	ResidentialCityTown int	NThe payroll job ID	Optional
AddressCountryjobTitle	string	Name ResidentialCountry of the job	NOptional
ProvincejobCode	ResidentialProvince string	NCode of the job	Optional
AddressCodeoccupationalCategory	ResidentialPostalCode string	NOccupation Category of the job	Optional
SameAsPhysicaloccupationalLevel	UseResidentialAsPostal string	NOccupational Level of the job within the category	Optional
UnitNumberjobOfoCode	PostalUnitNumber string	NOFO code of the job	Optional
ComplexjobGrade	PostalComplexNamestring	NGrade of the job	Optional
StreetNumbergradingType	PostalStreetNumber string	NGrading used for the job	Optional
AddressLine1positionExternalId	PostalStreetName int	NThe payroll position Id	Optional
AddressLine2positionTitle	PostalSuburbDistrict string	NPosition Name	Optional
AddressLine3positionCode	PostalCityTown string	NPosition Code	Optional
AddressCountryappointmentType	PostalCountry string	NHow the user is appointed in the position	Optional
ProvincestartDate	PostalProvince string	NStart date in the position	Optional
AddressCodeendDate	PostalCode string	NEnd date in the position, when empty, the user is not terminated	Optional
DisabledTypereasonForTermination	Disability string	NThe reason the user's employment has ended	Optional
GroupJoinDatestartDateInGroup	StartDateInGroup 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