UKG Pro Web Services API Guide

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.

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 = "jsmith@canco.com",
                            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

        

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.ultipro.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.ultipro.com/services/employeecanadiannewhire">
      <entities xmlns:b="http://www.ultipro.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>