Employee Employment Information Service

UKG Pro Web Services API Guide

Employee Employement Information 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 Employment Information web service and is intended for individuals who are familiar with software development and web service technologies.

Employee Employment Information Service API

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

Overview

This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 2010 using C# and XML (.NET Framework 3.0 or higher).

The following information describes the service requirements.

Service Specifications
ProtocolSimple Object Access Protocol (SOAP) 1.2
SSL SupportRequired
Signup and Licensing
Account RequiredUKG Pro Service Account or UKG Pro Web User with Web Services Permissions

Using an UKG Pro Service Account is recommended. For information regarding establishing and maintaining an UKG Pro Service Account, please refer to the document Maintaining Service Accounts located in the UKG Pro Technical Content section of the Ultimate Library under UKG Pro Web Services and APIs.Text.

Employee Employment Information Object

The Employee Employment Information object includes the following properties.

PropertyRequiredTypeDescription
EmploymentStatusYesChar (1)

A = Active

L = Leave of absence

O = On strike

R = Released/laid off

S = Suspended

Should not allow update to T. All terminations are to be done through the termination service.

ROEIssueReason
Char(2)

For Canada only.

Required if Status=L, O, R, or S

LeaveReason
Char(6)If EmploymentStatus=L, then LeaveReason is required.
StatusStartDateYesDatetime(8)Must be greater than the current status date.
StatusAnticipatedEnd
Datetime(8)Must be greater than the current status date.
PaySuspendedFrom
Datetime(8)

Must be less than PaySuspendedTo

Req. if PaySuspendedTo is completed

Successful submission forces Status=Suspended if not already chosen

PaySuspendedTo
Datetime(8)

Must be greater than PaySuspendedFrom

Req. if PaySuspendedFrom is completed

Successful submission forces Status=Suspended if not already chosen

ArrearsSuspendedFrom
Datetime(8)

Must be less than ArrearsSuspendedTo

Req. if ArrearsSuspendedTo is completed

ArrearsSuspendedTo
Datetime(8)

Must be greater than ArrearsSuspendedFrom

Req. if ArrearsSuspendedFrom is completed

PTOSuspendedFrom
Datetime(8)

Must be less than PTOSuspendedTo

Req if PTOSuspendedTo is completed

PTOSuspendedTo
Datetime(8)

Must be less than PTOSuspendedFrom

Req. if PTOSuspendedFrom is completed

PayAutomaticallyYesChar (1)
OriginalHireYesDatetime(8)
LastHireYesDatetime(8)Must be equal to or greater than Original Hire date
Job
Char(8)
JobStartYesDatetime(8)Must be equal to or greater than Original Hire date
SeniorityYesDatetime(8)Not compared to Original Hire - can be an older date
EarlyRetirement
Datetime(8)
RegularRetirement
Datetime(8)Not compared to Early Retirement Date - can be an older date
LastPerfReview
Datetime(8)Read only
NextPerfReview
Datetime(8)Read only
LastSalaryReview
Datetime(8)Read only
NextSalaryReview
Datetime(8)Read only
BeneSeniority
Datetime(8)
DeceasedYesChar(1)
DeceasedDate
Datetime(8)Required if Deceased=true
HCSONotCoveredYesChar(1)
HCSOStartDate
Datetime(8)Required if HCSONotCovered = Y
HCSOEndDate
Datetime(8)Required if HCSONotCovered = Y
FMLA_Code
Code
EmployeeIdentifier
Identifier
Weeks
Decimal

Quick Start

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

Prerequisites

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

  • An UKG Pro Service Account username and password OR an UKG Pro Web User username and password
  • The Customer API key from the UKG Pro Web Service administrative page.

If you use an UKG Pro Service Account:

  • You will need the User API key from the Service Account administrative page.
  • You must have appropriate permissions granted to the Service Account for the Employee Information service on the Service Account administrative page.

If you use an UKG Pro Web User account:

  • You will need the User API key from the Web Service administrative page.

Methods

This section introduces the API methods for the Employee Employment Information Web Service.

FindEmploymentInformation

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.

GetEmploymentInformationByEmployeeIdentifier

This method allows you to retrieve an individual employee’s employment information by providing an employee identifier.

UpdateEmploymentInformation

This method allows you to update employment information.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the EmployeeEmploymentInformation 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 Employment Information 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 SERVICE ACCOUNT OR WEB USER NAME ",
Password = "YOUR PASSWORD",
UserAPIkey = "YOUR USER API KEY",
CustomerAPIkey = "YOUR CUSTOMER API KEY"

//Example Quick Start Code Begin

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


    using ConsoleSample.EmployeeEmploymentInformationService;
    using ConsoleSample.LoginService;


    class Program
    {
        private const string ultiproTokenNamespace =
            "http://www.ultimatesoftware.com/foundation/authentication/ultiproToken";


        private const string ClientAccessKeyNamespace =
            "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey";


        static void Main(string[] args)
        {
            // Setup your user credentials.
            const string UserName = "";
            const string Password = "";
            const string UserApikey = "";
            const string CustomerApikey = "";


            // Create a proxy to the login service.
            var loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");


            try
            {
                // Submit the login request to authenticate the user.
                string message;
                string authenticationToken;
                var 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 employment information:
                    FindEmploymentInformation(CustomerApikey, authenticationToken);


                    // Update employment information:
                    UpdateEmploymentInformation(CustomerApikey, authenticationToken);
                }
                else
                {
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed");
                }


                loginClient.Close();


                Console.WriteLine("Press a key to exit");
                Console.ReadKey(true);
            }
            catch (Exception ex)
            {
                loginClient.Abort();
                Console.WriteLine("Exception: " + ex);
            }
        }


        private static void FindEmploymentInformation(string customerApiKey, string token)
        {
            // Create a proxy to the EmploymentInformation service.
            var client = new EmployeeEmploymentInformationClient("WSHttpBinding_IEmployeeEmploymentInformation");


            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(client.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader(
                            "ultiproToken",
                            ultiproTokenNamespace,
                            token));


                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader(
                            "ClientAccessKey",
                            ClientAccessKeyNamespace,
                            customerApiKey));


                    // Create a query object to find the employees.
                    var query =
                        new EmployeeQuery
                            {
                                // Set one or more properties to search.
                                LastName = "LIKE (ba%)",
                                FullOrPartTime = "=F",


                                // Set paging properties
                                PageSize = "10",
                                PageNumber = "1"
                            };


                    // Search for the employees.
                    EmploymentInformationFindResponse response =
                        client.FindEmploymentInformations(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.
                        Array employmentInfos = response.Results;


                        foreach (EmployeeEmploymentInformation employmentInfo in
                            employmentInfos)
                        {
                            foreach (EmploymentInformation info in
                                employmentInfo.EmploymentInformations)
                            {
                                Console.WriteLine(
                                    "Original Hire Date:" + info.OriginalHire +
                                    ", Employment Status:" + info.EmploymentStatus);
                            }
                        }


                        var 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 + ".");
                    }
                }


                client.Close();
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
                client.Abort();
            }
        }


        static void UpdateEmploymentInformation(string customerApiKey, string token)
        {
            // Create a proxy to the EmploymentInformation service.
            var client = new EmployeeEmploymentInformationClient("WSHttpBinding_IEmployeeEmploymentInformation");


            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(client.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader(
                            "ultiproToken",
                            ultiproTokenNamespace,
                            token));


                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader(
                            "ClientAccessKey",
                            ClientAccessKeyNamespace,
                            customerApiKey));


                    // Establish a person to update. 
                    // We are using the Employee Number to return the person.
                    var empno = new EmployeeNumberIdentifier { EmployeeNumber = "853296495" };


                    // Retrieve the persons employment information
                    EmploymentInformationGetResponse response =
                        client.GetEmploymentInformationByEmployeeIdentifier(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 the employee record is returned, update the desired data.
                        if (response.Results.Length > 0)
                        {
                            EmploymentInformation[] empInfos = response.Results;
                            Console.WriteLine("Employment Status:"
                                + empInfos[0].EmploymentStatus + ","
                                + empInfos[0].StatusStartDate);


                            // Update the employee data.
                            empInfos[0].LastHire = DateTime.Parse("01/01/2010");


                            // Submit the update.
                            EmploymentInformationUpdateResponse updateResponse =
                                client.UpdateEmploymentInformation(empInfos);


                            // Check the results to see if the update was successful.
                            if (updateResponse.OperationResult.HasErrors)
                            {
                                // Review each error.
                                foreach (OperationMessage message in
                                    updateResponse.OperationResult.Messages)
                                {
                                    Console.WriteLine("Error message: " + message.Message);
                                }
                            }
                            else
                            {
                                // The update was successfull.
                                Console.WriteLine("Update successful.");
                            }
                        }
                    }
                }


                client.Close();
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
                client.Abort();
            }
        }
    }
}
// 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.

FindEmploymentInformation

<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/employeeemploymentinformation/IEmployeeEmploymentInformation/FindEmploymentInformations</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">27e17fe3-29cb-48a0-a130-4bad41971dcb</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
 </s:Header>
 <s:Body>
 <FindEmploymentInformations xmlns="http://www.ultimatesoftware.com/services/employeeemploymentinformation">
  <query xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<b:CompanyCode /> 
<b:CompanyName /> 
<b:Country /> 
<b:EmployeeNumber /> 
<b:FirstName>like (a%)</b:FirstName> 
<b:FormerName /> 
<b:FullOrPartTime /> 
<b:Job /> 
<b:LastHire /> 
<b:LastName /> 
<b:Location /> 
<b:OrganizationLevel1 /> 
<b:OrganizationLevel2 /> 
<b:OrganizationLevel3 /> 
<b:OrganizationLevel4 /> 
<b:OriginalHire /> 
<b:PageNumber /> 
<b:PageSize /> 
<b:PayGroup /> 
<b:Status /> 
<b:SupervisorLastName /> 
<b:TerminationDate /> 
<b:TimeClockId /> 
</query>
</FindEmploymentInformations>
</s:Body>
</s:Envelope>

GetEmploymentInformationByEmployeeIdentifier

<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/employeeemploymentinformation/IEmployeeEmploymentInformation/GetEmploymentInformationByEmployeeIdentifier</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">27e17fe3-29cb-48a0-a130-4bad41971dcb</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
 </s:Header>
 <s:Body>
 <GetEmploymentInformationByEmployeeIdentifier xmlns="http://www.ultimatesoftware.com/services/employeeemploymentinformation">
  <employeeIdentifier xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" i:type="b:EmployeeNumberIdentifier">
<b:CompanyCode>C0014</b:CompanyCode> 
<b:EmployeeNumber>004446049</b:EmployeeNumber> 
</employeeIdentifier>
</GetEmploymentInformationByEmployeeIdentifier>
</s:Body>
</s:Envelope>

UpdateEmploymentInformation

<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/employeeemploymentinformation/IEmployeeEmploymentInformation/UpdateEmploymentInformation</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">27e17fe3-29cb-48a0-a130-4bad41971dcb</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
 </s:Header>
 <s:Body>
 <UpdateEmploymentInformation xmlns="http://www.ultimatesoftware.com/services/employeeemploymentinformation">
 <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
       <b:EmploymentInformation>
<b:ArrearsSuspendedFrom>0001-01-01T00:00:00</b:ArrearsSuspendedFrom> 
<b:ArrearsSuspendedTo>0001-01-01T00:00:00</b:ArrearsSuspendedTo> 
<b:BeneSeniority>0001-01-01T00:00:00</b:BeneSeniority> 
<b:Deceased>false</b:Deceased> 
<b:DeceasedDate>0001-01-01T00:00:00</b:DeceasedDate> 
<b:EarlyRetirement>0001-01-01T00:00:00</b:EarlyRetirement> 
<b:EmployeeIdentifier i:nil="true" /> 
<b:EmploymentStatus i:nil="true" /> 
<b:FMLA_Code i:nil="true" /> 
<b:HCSOEndDate>0001-01-01T00:00:00</b:HCSOEndDate> 
<b:HCSONotCovered>false</b:HCSONotCovered> 
<b:HCSOStartDate>0001-01-01T00:00:00</b:HCSOStartDate> 
<b:Job>SALES</b:Job> 
<b:JobStart>2013-04-08T00:00:00</b:JobStart> 
<b:LastHire>2013-04-08T00:00:00</b:LastHire> 
<b:LastPerfReview>2013-04-08T00:00:00</b:LastPerfReview> 
<b:LastSalaryReview>2013-04-08T00:00:00</b:LastSalaryReview> 
<b:LeaveReason i:nil="true" /> 
<b:NextPerfReview>2014-04-08T00:00:00</b:NextPerfReview> 
<b:NextSalaryReview>2014-04-08T00:00:00</b:NextSalaryReview> 
<b:OriginalHire>2013-04-08T00:00:00</b:OriginalHire> 
<b:PTOSuspendedFrom>0001-01-01T00:00:00</b:PTOSuspendedFrom> 
<b:PTOSuspendedTo>0001-01-01T00:00:00</b:PTOSuspendedTo> 
<b:PayAutomatically>false</b:PayAutomatically> 
<b:PaySuspendedFrom>0001-01-01T00:00:00</b:PaySuspendedFrom> 
<b:PaySuspendedTo>0001-01-01T00:00:00</b:PaySuspendedTo> 
<b:ROEIssueReason i:nil="true" /> 
<b:RegularRetirement>0001-01-01T00:00:00</b:RegularRetirement> 
  <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <c:KeyValueOfstringstring>
<c:Key /> 
<c:Value /> 
</c:KeyValueOfstringstring>
</b:SelfServiceProperties>
<b:Seniority>2013-04-08T00:00:00</b:Seniority> 
<b:StatusAnticipatedEnd>0001-01-01T00:00:00</b:StatusAnticipatedEnd> 
<b:StatusStartDate>2013-04-08T00:00:00</b:StatusStartDate> 
<b:Weeks>0</b:Weeks> 
</b:EmploymentInformation>
</entities>
</UpdateEmploymentInformation>
</s:Body>
</s:Envelope>