UKG Pro Web Services API Guide

Employee Termination Service

UKG Pro Employee Termination Service API

The UKG Pro Employee Termination Service API enables the user to programmatically retrieve and update Employee Termination information in UKG Pro.

Introduction

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

This document is intended for individuals who are familiar with software development and web service technologies.

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

Protocol: Simple Object Access Protocol (SOAP) 1.2
SSL Support: Required

Signup and Licensing

Account Required: UKG Pro Web User or UKG Pro Site Admin with API keys

Employee Termination Object

The Employee Termination object includes the following properties.

Property	Required	Type	Description
EmployeeIdentifier	Yes	Identifier
TerminationDate	Yes	DateTime(8)	Date must be after the LastHireDate
LastDayWorked		DateTime(8)	Defaults to termination date
PaidThroughDate	Yes	DateTime(8)	Defaults to termination date
TerminationReason	Yes	Code
EligibleForRehire		Boolean
InactivateAutoPay		Boolean
EligibleForSeverance		Boolean
InactivateDirectDeposit		Boolean
COBRAQualifyingEvent		Boolean
COBRADate		DateTime(8)
COBRAReason		Code
Notes		Text(16)
ROEIssueReason		Code

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve and update the Employee Termination information.

Prerequisites

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

UKG Pro Web service 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 Termination Web Service.

FindTermination

This method provides a way to query the web service based on one or more filter criteria. See the getting started guide for a list of query properties and operations supported.

Note that the paging properties may be set when using this method. You can specify the PageNumber and PageSize. The page number indicates which page you want to return and the PageSize refers to the number of records to return per PageNumber. You can return a maximum of 100 records per PageNumber.

GetTerminationByEmployeeIdentifier

This method allows you to retrieve an individual termination record by providing an employee identifier.

This is helpful if you are designing an application that is aware of the employees to retrieve or when you want to verify an update of the termination information.

TerminateEmployee

This method allows you to terminate an employee through an update to an individual record.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the EmployeeTermination Service and the Login 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 retrieving Employee Termination information from your UKG Pro data in a console application. You can copy the entire contents to a C# console application and update the following values and have an operable application.

See the methods section for an example of adding updates to your application.

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

//Example Quick Start Code Begin

namespace ConsoleTermination
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;

    using TerminationExample.Login;
    using TerminationExample.Termination;

    public class Program
    {
        public 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.");

                    // Find employees
                    FindTermination(CustomerAPIkey, AuthenticationToken);

                    // Get employees
                    GetTerminationByEmployeeIdentifier(CustomerAPIkey, AuthenticationToken);

                    // Update employees
                    TerminateEmployee(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);
            }
        }

        public static void FindTermination(string CustomerAPI, string Token)
        {
            try
            {
                // Create a proxy to the job service.
                EmployeeTerminationClient proxyTermination = new EmployeeTerminationClient("WSHttpBinding_IEmployeeTermination");

                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyTermination.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 a query object to find the employees.
                    EmployeeQuery query = new EmployeeQuery();

                    // Set one or more properties to search.
                    query.LastName = "LIKE (ba%)";
                    query.FullOrPartTime = "=F";

                    // Set paging properties
                    query.PageSize = "10";
                    query.PageNumber = "1";

                    // Search for the employees.
                    TerminationFindResponse response = proxyTermination.FindTerminations(query);

                    // Check the results of the find to see if there are any errors.
                    if (response.OperationResult.HasErrors)
                    {
                        // Review each error.
                        foreach (OperationMessage message in response.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
                    else
                    {
                        // If employee records are returned, loop through the results and write out the data.
                        foreach (EmployeeTerminationInfo employee in response.Results)
                        {
                            foreach (TerminationInfo terminationInfo in employee.TerminationInfo)
                            {
                                Console.WriteLine("Last name:" + employee.LastName +
                                    " Eligible for Rehire:" + terminationInfo.EligibleForRehire +
                                    " Last Date Worked:" + terminationInfo.LastDayWorked +
                                    " Termination Status:" + terminationInfo.Status);
                            }
                        }

                        PagingInfo pagingInfo = response.OperationResult.PagingInfo;

                        Console.WriteLine("The employee query returned a total of " + pagingInfo.TotalItems + " records.");
                        Console.WriteLine("The employee query returned a total of " + pagingInfo.PageTotal + " pages.");
                        Console.WriteLine("Each page contains " + pagingInfo.PageSize + " records.");
                        Console.WriteLine("The Results contain the records for page " + pagingInfo.CurrentPage + ".");
                    }
                }

                proxyTermination.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message);
            }
        }

        public static void GetTerminationByEmployeeIdentifier(string CustomerAPI, string Token)
        {
            try
            {
                // Create a proxy to the job service.
                EmployeeTerminationClient proxyTermination = new EmployeeTerminationClient("WSHttpBinding_IEmployeeTermination");

                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyTermination.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));

                    // Establish a person to update. We are using the Employee Number.
                    EmployeeNumberIdentifier empNo = new EmployeeNumberIdentifier();
                    empNo.EmployeeNumber = "686174418";

                    // Retrieve the person's user defiend fields.
                    TerminationGetResponse response = proxyTermination.GetTerminationByEmployeeIdentifier(empNo);

                    // Check the results of the find to see if there are any errors.
                    if (response.OperationResult.HasErrors)
                    {
                        // Review each error.
                        foreach (OperationMessage message in response.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
                    else
                    {
                        if (response.Results.Length > 0)
                        {
                            TerminationInfo[] terminationInfo = response.Results;
                            Console.WriteLine("Eligible for Rehire:" + terminationInfo[0].EligibleForRehire +
                                    " Last Date Worked:" + terminationInfo[0].LastDayWorked +
                                    " Termination Status:" + terminationInfo[0].Status);
                        }
                    }
                }

                proxyTermination.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message);
            }
        }

        public static void TerminateEmployee(string CustomerAPI, string Token)
        {
            try
            {
                // Create a proxy to the job service.
                EmployeeTerminationClient proxyTermination = new EmployeeTerminationClient("WSHttpBinding_IEmployeeTermination");

                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyTermination.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));

                    // Establish a person to update. We are using the Employee Number.
                    EmployeeNumberIdentifier empNo = new EmployeeNumberIdentifier();
                    empNo.EmployeeNumber = "686174418";

                    Termination[] termination = new Termination[1];
                    termination[0] = new Termination();

                    // Update the employee data.
                    termination[0].EmployeeIdentifier = empNo;
                    termination[0].EligibleForRehire = true;
                    termination[0].TerminationReason = "TRO";
                    termination[0].Notes = "Terminating this employee because they were transferred out.";
                    termination[0].LastDayWorked = DateTime.Now;
                    termination[0].PaidThroughDate = DateTime.Now;
                    termination[0].TerminationDate = DateTime.Now;
                            
                    // termination.RoeIssueReason is used to update Canadian Record of Employment (ROE)
                    // termination.CobraQualifyingEvent is used for an employee with deductions that qualify for COBRA
                    // termination.CobraDate is used for an employee with deductions that qualify for COBRA
                    // termination.CobraReason is used for an employee with deductions that qualify for COBRA
                            
                    // Submit the update
                    TerminationUpdateResponse updateResponse = proxyTermination.TerminateEmployee(termination);

                    // Check the results to see if the update was successful.
                    if (updateResponse.HasErrors)
                    {
                        foreach (Result result in updateResponse.Results)
                        {
                            foreach (OperationMessage message in result.Messages)
                            {
                                Console.WriteLine("Error message: " + message.Message + "Property: " + message.PropertyName);
                            }
                        }
                    }
                    else
                    {
                        // The update was succsessful. 
                        Console.WriteLine("Update successful.");
                    }
                }

                proxyTermination.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message);
            }
        }
    }
    ```
// Example Quick Start Code End

### XML Examples

The Authentication Service (http://<address>/services/LoginService) 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.

#### FindTermination

```xml
<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/employeetermination/IEmployeeTermination/FindTerminations</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">75115ff6-c290-4446-83b5-cfa3369b33bf</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <FindTerminations xmlns="http://www.ultipro.com/services/employeetermination">
      <query xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:CompanyCode i:nil="true" /> 
        <b:CompanyName i:nil="true" /> 
        <b:Country i:nil="true" /> 
        <b:EmployeeNumber i:nil="true" /> 
        <b:FirstName>like (a%)</b:FirstName> 
        <b:FormerName i:nil="true" /> 
        <b:FullOrPartTime i:nil="true" /> 
        <b:Job i:nil="true" /> 
        <b:LastHire i:nil="true" /> 
        <b:LastName /> 
        <b:Location i:nil="true" /> 
        <b:OrganizationLevel1 i:nil="true" /> 
        <b:OrganizationLevel2 i:nil="true" /> 
        <b:OrganizationLevel3 i:nil="true" /> 
        <b:OrganizationLevel4 i:nil="true" /> 
        <b:OriginalHire i:nil="true" /> 
        <b:PageNumber i:nil="true" /> 
        <b:PageSize i:nil="true" /> 
        <b:PayGroup i:nil="true" /> 
        <b:Status i:nil="true" /> 
        <b:SupervisorLastName i:nil="true" /> 
        <b:TerminationDate i:nil="true" /> 
        <b:TimeClockId i:nil="true" /> 
       </query>
     </FindTerminations>
   </s:Body>
</s:Envelope>

GetTerminationByEmployeeIdentifier

<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/employeetermination/IEmployeeTermination/GetTerminationByEmployeeIdentifier</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">e32d7cbb-e4d5-4806-b662-1235a37e31a2</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
  </s:Header>
  <s:Body>
    <GetTerminationByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeetermination">
      <employeeIdentifier xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" i:type="b:EmployeeNumberIdentifier">
        <b:CompanyCode>C0014</b:CompanyCode> 
        <b:EmployeeNumber>749828548</b:EmployeeNumber>
      </employeeIdentifier>
    </GetTerminationByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

TerminateEmployee

<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/employeetermination/IEmployeeTermination/TerminateEmployee</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">e32d7cbb-e4d5-4806-b662-1235a37e31a2</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <TerminateEmployee xmlns="http://www.ultipro.com/services/employeetermination">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:Termination>
          <b:CobraDate>0001-01-01T00:00:00</b:CobraDate>
          <b:CobraQualifyingEvent>false</b:CobraQualifyingEvent>
          <b:CobraReason i:nil="true" />
          <b:EligibleForRehire>false</b:EligibleForRehire>
          <b:EligibleForSeverance>false</b:EligibleForSeverance>
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode>
            <b:EmployeeNumber>004446049</b:EmployeeNumber>
          </b:EmployeeIdentifier>
          <b:HomeCompanyIdentifier i:type="b:CompanyCodeIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode>
          </b:HomeCompanyIdentifier>
          <b:InactivateAutopay>false</b:InactivateAutopay>
          <b:InactivateDirectDeposit>false</b:InactivateDirectDeposit>
          <b:LastDayWorked>0001-01-01T00:00:00</b:LastDayWorked>
          <b:Notes i:nil="true" />
          <b:PaidThroughDate>0001-01-01T00:00:00</b:PaidThroughDate>
          <b:RoeIssueReason i:nil="true" />
          <b:TerminationDate>0001-01-01T00:00:00</b:TerminationDate>
          <b:TerminationReason i:nil="true" />
        </b:Termination>
      </entities>
    </TerminateEmployee>
  </s:Body>
</s:Envelope>