UKG Pro Web Services API Guide

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. We recommend executing a find or get to retrieve the employment information first then submitting the object to the update method.

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.

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

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