Employee Canadian New Hire Service

Introduction

With UKG Pro Web Services, you can leverage your UKG Pro data for solving business application and integration needs.

This document describes how to use the Employee Canadian New Hire Web service and is intended for individuals who are familiar with software development and web service technologies.

Employee Canadian New Hire Service API

The UKG Pro Employee Canadian New Hire Service API enables the user to programmatically hire an employee into an UKG Pro component company based in Canada.

Overview

This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 2010 using C#.

The following information describes the service requirements.

Service Specifications
ProtocolSimple Object Access Protocol (SOAP) 1.2
SSL SupportRequired
Sign Up and Licensing
Account RequiredUKG Pro Web User or UKG Pro Site Admin with API keys

Employee Canadian New Hire Object

The employee Canadian new hire object includes the following properties.

PropertyRequiredTypeDescription
AboriginalPersonString

Y=Yes

N=No

Blank = Decline to answer

AddressLine1YesStringAddress line 1
AddressLine2StringAddress line 2
AlternateEmailAddressStringAlternate email address
AlternateTitleStringAlternate job title
BenefitSeniorityDateYesDateBenefit seniority date
BirthDateYesDateBirth date
CityYesStringAddress city
CompanyIdentifierYesReference

Identifier that represents an UKG Pro component company.

Select Company Code, Federal ID or Import code and provide the value.

CountryYesCode listAddress country code
DeductionBenefitGroupYesCode listDeduction / Benefit group code
EarningsGroupYesCode listEarnings group code
EmailAddressStringPrimary Email address
EmployeeNumberStringEmployee number. If the company employee number method is set to SSN, Time clock number or automatic, this field will be ignored.
EmployeeTypeYesCode listEmployee type code
EthnicityCode listEthnic origin code
FederalContributionMonthsIntEnter values of 1-11 if you wish to prorate the contribution to the pension plan.
FederalEmploymentInsuranceExemptBooleanIf true, employee is exempt from federal employment insurance.
FederalIncomeExemptBooleanIf true, the employee is exempt from federal income tax. Personal tax credit information will be ignored if this is true.

FederalPensionPlanExempt

BooleanIf true, the employee is exempt from the Canada Pension Plan. This can only be true if the FederalWithholdPensionPlan is false.
FederalWithholdPensionPlanBooleanIf true, the Canada Pension Plan will be withheld and reported.
FirstNameYesStringFirst name
FormerLastNameStringFormer last name
FullOrPartTimeYesCode list

Employee status

F = Full time

P = Part time

GenderYesCode list

Gender code.

System Delivered
M = Male
F = Female

Custom
The code for any custom gender defined by your company.

Validation
M and F are valid for all countries.

Other custom genders are country-specific, as defined by your System Administrator.

If the gender is defined for all countries, no further country validation is performed.

If the gender is defined for a specific country, that country must match the Country property.

HireDateYesDateDate of hire
HireSourceCode listHire source code
HomePhoneStringHome phone number. Exclude dashes and parentheses.
HourlyOrSalariedYesCode list

Employee’s pay type

H = Hourly

S = Salaried

JobCodeYesCode listJob code
JobGroupCode listJob group code
LastNameYesStringLast name
LocalUnionCode listLocal union code
LocationCodeYesCode listLocation code
MailStopStringMail stop
MaritalStatusCode listMarital Status code
MiddleNameStringMiddle name
NationalUnionCode listNational union code
NextPerformanceReviewDateDateDate of next performance review
NextSalaryReviewDateDateDate of next salary review
OrgLevel1Code listOrganizational 1 code
OrgLevel2Code listOrganizational 2 code
OrgLevel3Code listOrganizational 3 code
OrgLevel4Code listOrganizational 4 code
PayAutomaticallyBooleanIf true, selects the employee to be auto paid
PayGroupYesCode listPay group code
PayRateYesDecimalEmployee’s rate of pay. Set the PayRateType accordingly.
PayRateTypeYesCode list

Type of pay rate entered in the PayRate.

H=Hourly

P=Period

W=Weekly

Y=Yearly (Annual)

PayStatementLanguageYesCode list

Preferred language for the employee’s pay statement.

EN = English

FR = French

PersonalAdditionalTaxDecimalAdditional personal tax to be deducted.
PersonalAnnualDeductionToIncomeDecimalAdditional annual deduction to income when employee requests a reduction in tax deductions.
PersonalCommissionedEmployeeBooleanIf true, employee is commissioned claiming expenses.
PersonalEstimatedCommissionExpenseDecimalIf a commissioned employee, the estimated amount of commission expense.
PersonalEstimatedRemunerationDecimalIf a commissioned employee, the estimated total remuneration.
PersonalEstimatedYearlyDeductionAmountDecimalIf a commissioned employee, the estimated total deduction amount for the year.
PersonalIncomeLessthanTotalClaimBoolean

If true, the total income is less than total claim amount.

If true, all other personal tax credit properties are ignored.

PersonalOtherFederalCreditsDecimalOther federal tax credits when employee requests a reduction in tax deductions
PersonalPrescribedZoneAmountDecimalDeduction amount for living in a prescribed zone.
PersonalTotalClaimAmountDecimalTotal claim amount if any when not using the basic personal amount.
PersonalUseBasicAmountBoolean

If true, the basic personal amount will be used for the person tax credits.

If true, PersonalTotalClaimAmount and PersonalIncomeLessthanTotalClaim will be ignored.

PreferredFirstNameStringPreferred first name
PrefixCode listPrefix name code
ProjectCode listProject code
ProvincialAdditionalTaxDecimalAdditional personal provincial tax to be deducted.
ProvincialAnnualDeductionToIncomeDecimalAdditional annual deduction to income when employee requests a reduction in tax deductions.
ProvincialIncomeExemptBooleanIf true, the employee is exempt from provincial income tax. Provincial personal tax credits will be ignored if true.
ProvincialIncomeLessthanTotalClaimBoolean

If true, the total income is less than total claim amount.

If true, all other personal tax credit properties are ignored.

ProvincialNumberofDependentsIntNumber of dependents. Valid for the provinces of Manitoba and Ontario.
ProvincialOtherTaxCreditsDecimalOther provincial tax credits when employee requests a reduction in tax deductions
ProvincialPrescribedZoneAmountDecimalDeduction amount for living in a prescribed zone and/or deductible support payments.
ProvincialTotalClaimAmountDecimalTotal claim amount if any when not using the basic personal amount.
ProvincialUseBasicAmountBoolean

If true, the basic personal amount will be used for the person tax credits.

If true, ProvincialTotalClaimAmount and ProvincialIncomeLessthanTotalClaim will be ignored.

QuebecContributionMonthsIntEnter values of 1-11 if you wish to prorate the contribution to the Quebec pension plan.
QuebecParentalInsuranceExemptBooleanIf true, the employee is exempt from the Parental Insurance Plan when the work location province is Quebec.
QuebecPensionPlanExemptBooleanIf true, the employee is exempt from the Quebec pension plan when the work location province is Quebec.
QuebecWithholdPensionPlanBoolean

If true, the Quebec Pension Plan will be withheld and reported.

If true, the QuebecPensionPlanExempt must be false.

ScheduledHoursYesDecimalScheduled hours
SeniorityDateYesDateDate of seniority
ShiftCodeCode listShift code
ShiftGroupCode listShift group code
SINYesStringSocial Insurance Number
SSNStringSocial Security Number
StateOrProvinceYesCode listState or Province code
SuffixCode listSuffix name code
SupervisorReferenceID that represents a person that is the supervisor
TimeClockString

Time clock code.

Required if the employee number method is set to time clock.

VisibleMinorityMemberString

Is the employee a member of a visible minority?

Y=Yes

N=No

Blank = Decline to answer

WorkExtensionStringWork phone extension
WorkPhoneStringWork phone. Exclude dashes and parentheses.
ZipOrPostalCodeYesStringZip / Postal code

Quick Start

This section provides steps for creating a sample application in your development environment to hire an employee in a Canadian based company.

Prerequisites

In order to use the service, you will need the following items:

  • UKG Pro Web user account and password
  • User API key and Customer API key from the UKG Pro Web service administrative page

Methods

This section introduces the API methods for the Employee New Hire Web Service.

NewHireCanada

This method provides a way to hire an employee to a Canadian based company in UKG Pro. You must provide the minimum required fields listed in the new hire object in order to successfully hire an employee.

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the Login Service and the Canadian New Hire service. In your development environment, add the service references.

In Visual Studio, select the Add Service Reference menu item from the Project menu. Once you enter the service information you should have the references display in the solution explorer.

Created service reference
Created service reference

Example Code

The following code is an example of adding a new employee in a console application. Copy the entire contents to a C# console application and update the following values to build an operable application.

UserName = "YOUR WEB USER NAME ",
Password = "YOUR PASSWORD",
UserAPIkey = "YOUR USER API KEY",
CustomerAPIkey = "YOUR CUSTOMER API KEY"


//Example Quick Start Code Begin

using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Text;
using EmployeeCanadianNewHire.LoginService;
using EmployeeCanadianNewHire.NewHireCanadianService;
 
namespace EmployeeCanadianNewHire
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                // Setup your user credentials.
                string UserName = "";
                string Password = "";
                string UserAPIkey = "";
                string CustomerAPIkey = "";
                string Message = "";
                string AuthenticationToken = "";
 
                // Create a proxy to the login service.
                LoginServiceClient loginClient = new
                LoginServiceClient("WSHttpBinding_ILoginService");
 
                // Submit the login request to authenticate the user.
                AuthenticationStatus loginRequest = loginClient.Authenticate
                    (CustomerAPIkey, Password, UserAPIkey, UserName, out Message, out AuthenticationToken);
 
                if (loginRequest == AuthenticationStatus.Ok)
                {
                    // User is authenticated and the authentication token is provided.
                    Console.WriteLine("User authentication successful.");
 
                    // Hire an employee
                    NewHire(CustomerAPIkey, AuthenticationToken);
 
                }
                else
                {
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed: " + Message);
                }
                loginClient.Close();
                Console.WriteLine("Press a key to exit");
                Console.ReadKey(true);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message.ToString());
            }
 
        }
 
        static void NewHire(string CustomerAPI, string Token)
        {
            try
            {
                //Create a proxy to the new hire
                EmployeeCanadianNewHireClient proxyHire = new
					EmployeeCanadianNewHireClient("WSHttpBinding_IEmployeeCanadianNewHire");
 
                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyHire.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("ultiproToken",
                        "http://www.ultimatesoftware.com/foundation/authentication/ultiproToken", Token));
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("ClientAccessKey",
                        "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey",
							CustomerAPI));
 
                    // Create an employee and set the values
                    var newHire =
                        new CanadianEmployee
                        {
                            AboriginalPerson = "N",
                            AddressLine1 = "123 Main St",
                            AddressLine2 = string.Empty,
                            AlternateEmailAddress = string.Empty,
                            AlternateTitle = "Sales Rep",
                            BenefitSeniorityDate = new DateTime(2012, 4, 1),
                            BirthDate = new DateTime(1970, 1, 1),
                            City = "Toronto",
                            CompanyIdentifier = new CompanyCodeIdentifier { CompanyCode = "CW1" },
                            Country = "CAN",
                            DeductionBenefitGroup = "CALL",
                            EarningsGroup = "CALL",
                            EmailAddress = "[email protected]",
                            EmployeeNumber = "68947",
                            EmployeeType = "REG",
                            Ethnicity = "1",
                            FederalEmploymentInsuranceExempt = false,
                            FederalIncomeExempt = false,
                            FederalPensionPlanExempt = false,
                            FederalWithholdPensionPlan = true,
                            FirstName = "Jacob",
                            FormerLastName = string.Empty,
                            FullOrPartTime = "F",
                            Gender = "M",
                            HireDate = new DateTime(2012, 4, 1),
                            HireSource = string.Empty,
                            HomePhone = "4168611100",
                            HourlyOrSalaried = "S",
                            JobCode = "CANJOB4",
                            JobGroup = "",
                            LastName = "Smith",
                            LocalUnion = string.Empty,
                            LocationCode = "TORONT",
                            MailStop = string.Empty,
                            MaritalStatus = "M",
                            MiddleName = "R",
                            NationalUnion = string.Empty,
                            NextPerformanceReviewDate = new DateTime(2012, 10, 1),
                            NextSalaryReviewDate = new DateTime(2012, 10, 1),
                            OrgLevel1 = "CANR01",
                            OrgLevel2 = "CAN005",
                            OrgLevel3 = string.Empty,
                            OrgLevel4 = string.Empty,
                            PayAutomatically = false,
                            PayGroup = "CANWEB",
                            PayRate = 50000.00m,
                            PayRateType = "Y",
                            PayStatementLanguage = "EN",
                            PersonalUseBasicAmount = true,
                            PreferredFirstName = "Jay",
                            ProvincialIncomeExempt = false,
                            ProvincialNumberofDependents = 2,
                            ProvincialUseBasicAmount = true,
                            ScheduledHours = 80m,
                            SeniorityDate = new DateTime(2012, 4, 1),
                            ShiftCode = string.Empty,
                            ShiftGroup = string.Empty,
                            SIN = "162637201",
                            SSN = string.Empty,
                            StateOrProvince = "ON",
                            Suffix = string.Empty,
                            Supervisor = new EmployeeNumberIdentifier { EmployeeNumber = "555655159" },
                            TimeClock = string.Empty,
                            VisibleMinorityMember = "N",
                            WorkExtension = "289",
                            WorkPhone = "4168611200",
                            ZipOrPostalCode = "M5H3L5"
                        };
 
                    //Add the new hire
                    CreateResponse createresponse = proxyHire.NewHireCanada(new[] { newHire });
 
                    //Check the operational results for any errors
                    if (createresponse.OperationResult.HasErrors)
                    {
                        // Review each error.
                        foreach (OperationMessage message in createresponse.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
 
                    //Check the response results for any errors
                    if (createresponse.HasErrors)
                    {
                        foreach (var result in createresponse.Results)
                        {
                            Console.WriteLine("HasErrors: " + result.HasErrors);
                            Console.WriteLine("HasWarnings: " + result.HasWarnings);
                            Console.WriteLine("Success: " + result.Success);
 
                            foreach (var message in result.Messages)
                            {
                                Console.WriteLine("\tCode: " + message.Code);
                                Console.WriteLine("\tMessage: " + message.Message);
                                Console.WriteLine("\tPropertyName: " + message.PropertyName);
                                Console.WriteLine("\tSeverity: " + message.Severity + "\n");
                            }
                        }
                    }
                    else
                    {
                        Console.WriteLine("New hire success.");
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message.ToString());
            }
        }
    }
}

// Example Quick Start Code End

XML Examples

Authentication Service (http://<address>/services/LoginService())
The Authentication Service is required to get the Token needed for all Core Web Service Calls. Please refer to the UKG Pro Login Service API Guide for further information.

NewHireCanada


<s:Envelope xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:s="http://www.w3.org/2003/05/soap-envelope">
  <s:Header>
  <a:Action s:mustUnderstand="1">http://www.ultimatesoftware.com/services/employeecanadiannewhire/IEmployeeCanadianNewHire/NewHireCanada</a:Action> 
  <ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2cc9adb0-2eb3-4132-bce5-d47f9ec2bd02</ultiproToken> 
  <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
  </s:Header>
  <s:Body>
  <NewHireCanada xmlns="http://www.ultimatesoftware.com/services/employeecanadiannewhire">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:CanadianEmployee>
  <b:AboriginalPerson i:nil="true" /> 
  <b:AddressLine1>123 Maple</b:AddressLine1> 
  <b:AddressLine2 i:nil="true" /> 
  <b:AlternateEmailAddress i:nil="true" /> 
  <b:AlternateTitle i:nil="true" /> 
  <b:BenefitSeniorityDate>2013-04-13T00:00:00</b:BenefitSeniorityDate> 
  <b:BirthDate>1980-01-01T00:00:00</b:BirthDate> 
  <b:City>Toronto</b:City> 
  <b:CompanyIdentifier i:type="b:CompanyCodeIdentifier">
  <b:CompanyCode>CW1</b:CompanyCode> 
  </b:CompanyIdentifier>
  <b:Country>CAN</b:Country> 
  <b:DeductionBenefitGroup>CALL</b:DeductionBenefitGroup> 
  <b:EarningsGroup>CALL</b:EarningsGroup> 
  <b:EmailAddress i:nil="true" /> 
  <b:EmployeeNumber>2468</b:EmployeeNumber> 
  <b:EmployeeType>REG</b:EmployeeType> 
  <b:Ethnicity i:nil="true" /> 
  <b:FederalContributionMonths>0</b:FederalContributionMonths> 
  <b:FederalEmploymentInsuranceExempt>false</b:FederalEmploymentInsuranceExempt> 
  <b:FederalIncomeExempt>false</b:FederalIncomeExempt> 
  <b:FederalPensionPlanExempt>false</b:FederalPensionPlanExempt> 
  <b:FederalWithholdPensionPlan>false</b:FederalWithholdPensionPlan> 
  <b:FirstName>John</b:FirstName> 
  <b:FormerLastName i:nil="true" /> 
  <b:FullOrPartTime>F</b:FullOrPartTime> 
  <b:Gender>M</b:Gender> 
  <b:HireDate>2013-04-13T00:00:00</b:HireDate> 
  <b:HireSource i:nil="true" /> 
  <b:HomePhone>5554449999</b:HomePhone> 
  <b:HourlyOrSalaried>S</b:HourlyOrSalaried> 
  <b:JobCode>CANJOB4</b:JobCode> 
  <b:JobGroup i:nil="true" /> 
  <b:LastName>Tester</b:LastName> 
  <b:LocalUnion i:nil="true" /> 
  <b:LocationCode>TORONT</b:LocationCode> 
  <b:MailStop i:nil="true" /> 
  <b:MaritalStatus i:nil="true" /> 
  <b:MiddleName>D</b:MiddleName> 
  <b:NationalUnion i:nil="true" /> 
  <b:NextPerformanceReviewDate>2014-04-13T00:00:00</b:NextPerformanceReviewDate> 
  <b:NextSalaryReviewDate>2014-04-13T00:00:00</b:NextSalaryReviewDate> 
  <b:OrgLevel1 i:nil="true" /> 
  <b:OrgLevel2 i:nil="true" /> 
  <b:OrgLevel3 i:nil="true" /> 
  <b:OrgLevel4 i:nil="true" /> 
  <b:PayAutomatically>false</b:PayAutomatically> 
  <b:PayGroup>CANWEB</b:PayGroup> 
  <b:PayRate>500000</b:PayRate> 
  <b:PayRateType>Y</b:PayRateType> 
  <b:PayStatementLanguage>EN</b:PayStatementLanguage> 
  <b:PersonalAdditionalTax>0</b:PersonalAdditionalTax> 
  <b:PersonalAnnualDeductionToIncome>0</b:PersonalAnnualDeductionToIncome> 
  <b:PersonalCommissionedEmployee>false</b:PersonalCommissionedEmployee> 
  <b:PersonalEstimatedCommissionExpense>0</b:PersonalEstimatedCommissionExpense> 
  <b:PersonalEstimatedRemuneration>0</b:PersonalEstimatedRemuneration> 
  <b:PersonalEstimatedYearlyDeductionAmount>0</b:PersonalEstimatedYearlyDeductionAmount> 
  <b:PersonalIncomeLessthanTotalClaim>false</b:PersonalIncomeLessthanTotalClaim> 
  <b:PersonalOtherFederalCredits>0</b:PersonalOtherFederalCredits> 
  <b:PersonalPrescribedZoneAmount>0</b:PersonalPrescribedZoneAmount> 
  <b:PersonalTotalClaimAmount>0</b:PersonalTotalClaimAmount> 
  <b:PersonalUseBasicAmount>false</b:PersonalUseBasicAmount> 
  <b:PreferredFirstName>John</b:PreferredFirstName> 
  <b:Prefix i:nil="true" /> 
  <b:Project i:nil="true" /> 
  <b:ProvincialAdditionalTax>0</b:ProvincialAdditionalTax> 
  <b:ProvincialAnnualDeductionToIncome>0</b:ProvincialAnnualDeductionToIncome> 
  <b:ProvincialIncomeExempt>false</b:ProvincialIncomeExempt> 
  <b:ProvincialIncomeLessthanTotalClaim>false</b:ProvincialIncomeLessthanTotalClaim> 
  <b:ProvincialNumberofDependents>0</b:ProvincialNumberofDependents> 
  <b:ProvincialOtherTaxCredits>0</b:ProvincialOtherTaxCredits> 
  <b:ProvincialPrescribedZoneAmount>0</b:ProvincialPrescribedZoneAmount> 
  <b:ProvincialTotalClaimAmount>0</b:ProvincialTotalClaimAmount> 
  <b:ProvincialUseBasicAmount>false</b:ProvincialUseBasicAmount> 
  <b:QuebecContributionMonths>0</b:QuebecContributionMonths> 
  <b:QuebecParentalInsuranceExempt>false</b:QuebecParentalInsuranceExempt> 
  <b:QuebecPensionPlanExempt>false</b:QuebecPensionPlanExempt> 
  <b:QuebecWithholdPensionPlan>false</b:QuebecWithholdPensionPlan> 
  <b:SIN i:nil="true" /> 
  <b:SINExpiryDate>0001-01-01T00:00:00</b:SINExpiryDate> 
  <b:SSN i:nil="true" /> 
  <b:ScheduledHours>80</b:ScheduledHours> 
  <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <c:KeyValueOfstringstring>
  <c:Key /> 
  <c:Value /> 
  </c:KeyValueOfstringstring>
  </b:SelfServiceProperties>
  <b:SeniorityDate>2013-04-13T00:00:00</b:SeniorityDate> 
  <b:ShiftCode i:nil="true" /> 
  <b:ShiftGroup i:nil="true" /> 
  <b:StateOrProvince>ON</b:StateOrProvince> 
  <b:Suffix i:nil="true" /> 
  <b:Supervisor i:nil="true" /> 
  <b:TimeClock i:nil="true" /> 
  <b:VisibleMinorityMember i:nil="true" /> 
  <b:WorkExtension i:nil="true" /> 
  <b:WorkPhone>5558884444</b:WorkPhone> 
  <b:ZipOrPostalCode>M5H3L5</b:ZipOrPostalCode> 
  </b:CanadianEmployee>
  </entities>
  </NewHireCanada>
  </s:Body>
  </s:Envelope>