UKG Pro Web Services API Guide

Employee Compensation Service

Employee Compensation Service API

The UKG Pro Employee Compensation Service API enables the user to programmatically retrieve and update employee compensation 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 2008 using C# and XML (.NET Framework 3.0 or higher).

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: One of the following is required:

UKG Pro Web User with Web Services permissions
UKG Pro Service Account

Using a UKG Pro Service Account is recommended. For information regarding establishing and maintaining a UKG Pro Service Account, refer to the Manage Service Accounts guide located in the UKG Pro Learning Center (Home > Content > System Management > Web Services).

Employee Compensation Object

The employee compensation object includes the following properties.

Property	Required	Type	Description
Annual		Decimal	Employee’s annual compensation. Required on updates if `RateChangeType = Y`.
EffectiveDate	Yes	Date	Required for updates. The effective date of the compensation change.
Hourly		Decimal	Employee’s hourly rate. Required on updates if `RateChangeType = H`.
PayFrequency	Yes	Code list	Pay frequency code associated with the pay group.
			B = Biweekly
			M = Monthly
			S = Semi-monthly
			W = Weekly
PayGroup	Yes	Code list	Employee’s pay group
PercentChange		String	Percentage increase or decrease amount. Enter whole numbers. For example, enter 3.5 for an increase of 3 ½ percent.
Period		Decimal	Employee’s period compensation. Required on updates if `RateChangeType = P`.
RateChangeType		Code list	The type of compensation change. If provided, the corresponding property must have a value.
			Y = Annual
			H = Hourly
			P = Period
			W = Weekly
ReasonCode		Code list	Required for updates. Reason code for compensation change.
ScheduledHours	Yes	Decimal	Employee’s scheduled hours.
Weekly		Decimal	Employee’s weekly compensation. Required on updates if `RateChangeType = W`.
EmployeeIdentifier	Yes	Reference	ID that represents a person.

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve and update the employee compensation 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 Compensation 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 Compensation Web Service.

FindCompensations

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.

GetCompensationByEmployeeIdentifier

This method allows you to retrieve an individual compensation 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 plan to execute an update of some of the compensation information.

UpdateCompensation

This method allows you to update the compensation information. We recommend executing a find or get to retrieve the compensation information first then submitting the object to the update method.

C# Example

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 Compensation 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 compensation 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 ConsoleCompensation
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;
    using ConsoleSample.EmployeeCompensationService;
    using ConsoleSample.LoginService;

    class Program
    {
        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
            {
                string message;
                string authenticationToken;

                // 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 compensation:
                    FindCompensation(CustomerApikey, authenticationToken);

                    // Update compensation:
                    UpdateEmployeeCompensation(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);
                loginClient.Abort();
            }
        }

        private static void FindCompensation(string customerApiKey, string token)
        {
            // Create a proxy to the compensation service.
            var client =
new EmployeeCompensationClient("WSHttpBinding_IEmployeeCompensation");

            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(client.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",
                            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.
                    CompensationFindResponse response = client.FindCompensations(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 employees = response.Results;

                        foreach (EmployeeCompensation employee in employees)
                        {
                            foreach (Compensation comp in employee.Compensations)
                            {
                                Console.WriteLine("Last name:" + employee.LastName + "Annual Comp:" + comp.Annual);
                            }
                        }

                        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 ex)
            {
                Console.WriteLine("Exception: " + ex);
                client.Abort();
            }
        }

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

            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(client.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",
                            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 compensation
                    CompensationGetResponse response =
                        client.GetCompensationByEmployeeIdentifier(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)
                        {
                            Compensation[] compensation = response.Results;
                            Console.WriteLine("Compensation:"
                                + compensation[0].Annual + ","
                                + compensation[0].PayFrequency);

                            // Update the employee data.
                            compensation[0].ScheduledHours = 40.0m;

                            // Submit the update.
                            CompensationUpdateResponse updateResponse =
                                client.UpdateCompensation(compensation);

                            // 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

The Authentication Service (http://

/services/LoginService) is required to get the Token needed for all Core Web Service Calls. Please refer to the UltiPro Login Service API Guide for further information.

FindCompensations

<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/employeecompensation/IEmployeeCompensation/FindCompensations</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">c7c54995-2351-4648-b3d4-cd2c174a1e44</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <FindCompensations xmlns="http://www.ultipro.com/services/employeecompensation">
      <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>
    </FindCompensations>
  </s:Body>
</s:Envelope>

GetCompensationByEmployeeIdentifier

<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/employeecompensation/IEmployeeCompensation/GetCompensationByEmployeeIdentifier</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">c7c54995-2351-4648-b3d4-cd2c174a1e44</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <GetCompensationByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeecompensation">
      <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>555667788</b:EmployeeNumber> 
      </employeeIdentifier>
    </GetCompensationByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

UpdateCompensation

<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/employeecompensation/IEmployeeCompensation/UpdateCompensation</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">c7c54995-2351-4648-b3d4-cd2c174a1e44</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <UpdateCompensation xmlns="http://www.ultipro.com/services/employeecompensation">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:Compensation>
          <b:Annual>50000</b:Annual> 
          <b:EffectiveDate>2013-04-11T00:00:00</b:EffectiveDate> 
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode> 
            <b:EmployeeNumber>555667788</b:EmployeeNumber> 
          </b:EmployeeIdentifier>
          <b:Hourly>48.08</b:Hourly> 
          <b:PayFrequency i:nil="true" /> 
          <b:PayGroup i:nil="true" /> 
          <b:PercentChange>5</b:PercentChange> 
          <b:Period>0</b:Period> 
          <b:RateChangeType i:nil="true" /> 
          <b:ReasonCode 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:Weekly>961.53</b:Weekly> 
        </b:Compensation>
      </entities>
    </UpdateCompensation>
  </s:Body>
</s:Envelope>