UKG Pro Web Services API Guide

Employee User Defined Fields Service

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.

Employee User-Defined Fields Object

The Employee User-Defined Fields object includes the following properties:

Employee	Company	International
`EepUDField01`	`EecUDField01` `char(10)`	`EinUDField01` `varchar(25)`
`EepUDField02`	`EecUDField02` `char(10)`	`EinUDField02` `varchar(25)`
`EepUDField03`	`EecUDField03` `char(10)`	`EinUDField03` `money(8)`
`EepUDField04`	`EecUDField04` `varchar(25)`	`EinUDField04` `money(8)`
`EepUDField05`	`EecUDField05` `varchar(25)`	`EinUDField05` `datetime(8)`
`EepUDField06`	`EecUDField06` `datetime(8)`	`EinUDField06` `datetime(8)`
`EepUDField07`	`EecUDField07` `datetime(8)`	`EinUDField07` `varchar(15)`
`EepUDField08`	`EecUDField08` `datetime(8)`	`EinUDField08` `varchar(25)`
`EepUDField09`	`EecUDField09` `money(8)`	`EinUDField09` `varchar(25)`
`EepUDField10`	`EecUDField10` `money(8)`	`EinUDField10` `money(8)`
`EepUDField11`	`EecUDField11` `char(10)`	`EinUDField11` `money(8)`
`EepUDField12`	`EecUDField12` `char(10)`	`EinUDField12` `datetime(8)`
`EepUDField13`	`EecUDField13` `char(10)`	`EinUDField13` `datetime(8)`
`EepUDField14`	`EecUDField14` `varchar(25)`	`EinUDField14` `varchar(15)`
`EecUDField15`
`EecUDField16`
`EecUDField17`
`EecUDField18`
`EecUDField19`
`EecUDField20`
`EecUDField21`
`EecUDField22`
`EecUDField23`
`EecUDField24`
`EecUDField25`
`EecUDField26`
`EecUDField27`
`EecUDField28`
`EecUDField29`

Quick Start

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

Prerequisites

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

A UKG Pro Service Account username and password or a UKG Pro Web User username and password
The Customer API key from the UKG Pro Web Service administrative page

If you use a 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 User Defined Fields service on the Service Account administrative page.

If you use a 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 User-Defined Fields Web Service.

FindUserDefinedFields

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.

GetUserDefinedFieldsByEmployeeIdentifier

This method allows you to retrieve an individual user-defined fields result by providing an employee identifier.

UpdateUserDefinedFields

This method allows you to update user-defined fields.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the EmployeeUserDefinedFields 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 User-Defined Fields 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 ConsoleSample
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Channels;

    using ConsoleSample.EmployeeUserDefinedFieldsService;
    using ConsoleSample.LoginService;

    public class Program2
    {
        private const string UltiproTokenNamespace = "http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken";

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

        public static void Main2(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 user defined fields:
                    FindUserDefinedFields(CustomerApIkey, authenticationToken);

                    // Get user defined fields:
                    GetUserDefinedFieldsByEmployeeIdentifier(CustomerApIkey, authenticationToken);

                    // Update user defined fields:
                    UpdateUserDefinedFields(CustomerApIkey, authenticationToken);
                }
                else
                {
                    // User authentication has failed. Review the message for details.
                    Console.WriteLine("User authentication failed: {0}", message);
                }

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

        public static void FindUserDefinedFields(string customerApi, string token)
        {
            // Create a proxy to the user defined fields service.
            var proxyUserDefinedFields = new EmployeeUserDefinedFieldsClient("WSHttpBinding_IEmployeeUserDefinedFields");

            try
            {
                // Add the headers for the Customer API key and authentication token.
                using (new System.ServiceModel.OperationContextScope(proxyUserDefinedFields.InnerChannel))
                {
                    OperationContext.Current.OutgoingMessageHeaders.Add(
                        MessageHeader.CreateHeader("UltiProToken", UltiproTokenNamespace, token));

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

                    // 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.
                    UserDefinedFieldsFindResponse response = proxyUserDefinedFields.FindUserDefinedFields(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 (EmployeeUserDefinedFields employee in response.Results)
                        {
                            foreach (UserDefinedFields fields in employee.UserDefinedFields)
                            {
                                Console.WriteLine("Last name:" + employee.LastName +
                                    " Company User Defined Field 1:" + fields.EecUdField01 +
                                    " Person User Defined Field 1:" + fields.EepUdField01 +
                                    " Internal Employee User Defined Field 1:" + fields.EinUdField01);
                            }
                        }

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

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

        public static void GetUserDefinedFieldsByEmployeeIdentifier(string customerApi, string token)
        {
            // Create a proxy to the user defined fields service:
            var proxyUserDefinedFields = new EmployeeUserDefinedFieldsClient("WSHttpBinding_IEmployeeUserDefinedFields");

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

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

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

                    // Retrieve the person's user defiend fields.
                    UserDefinedFieldsGetResponse response = proxyUserDefinedFields.GetUserDefinedFieldsByEmployeeIdentifier(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)
                        {
                            UserDefinedFields[] fields = response.Results;
                            Console.WriteLine(
                                "Company User Defined Fields 1: {0} Person User Defined Fields 1: {1} International Employee User Defined Fields 1: {2}",
                                fields[0].EecUdField01,
                                fields[0].EepUdField01,
                                fields[0].EinUdField01);
                        }
                    }
                }

                proxyUserDefinedFields.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: {0}", ex.Message);
                proxyUserDefinedFields.Abort();
            }
        }

        public static void UpdateUserDefinedFields(string customerApi, string token)
        {
            // Create a proxy to the user defined fields service:
            var proxyUserDefinedFields =
                new EmployeeUserDefinedFieldsClient("WSHttpBinding_IEmployeeUserDefinedFields");

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

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

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

                    UserDefinedFieldsGetResponse response = proxyUserDefinedFields.GetUserDefinedFieldsByEmployeeIdentifier(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: {0}", message.Message);
                        }
                    }
                    else
                    {
                        // If the employee record is returned, update the desired data
                        if (response.Results.Length > 0)
                        {
                            UserDefinedFields[] fields = response.Results;
                            Console.WriteLine(
                                "Company User Defined Fields 1: {0} Person User Defined Fields 1: {1} International Employee User Defined Fields 1: {2}",
                                fields[0].EecUdField01,
                                fields[0].EepUdField01,
                                fields[0].EinUdField01);

                            // Update the employee data.
                            // Only need to update fields that are changing since I did a get operation first
                            fields[0].EecUdField01 = "Field 1";
                            fields[0].EepUdField01 = "Field 2";
                            fields[0].EinUdField01 = "Field 3";

                            // Submit the update
                            UserDefinedFieldsUpdateResponse updateResponse = proxyUserDefinedFields.UpdateUserDefinedFields(fields);

                            // 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: {0} Property: {1}",
                                            message.Message,
                                            message.PropertyName);
                                    }
                                }
                            }
                            else
                            {
                                // The update was succsessful. 
                                Console.WriteLine("Update successful.");
                            }
                        }
                    }
                }

                proxyUserDefinedFields.Close();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception:" + ex.Message);
                proxyUserDefinedFields.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 UKG Pro Login Service API Guide for further information.

FindUserDefinedFields

<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/employeeuserdefinedfields/IEmployeeUserDefinedFields/FindUserDefinedFields</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">dd5937d6-13ee-4704-af36-4764e342f0cb</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">J43CW</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <FindUserDefinedFields xmlns="http://www.ultipro.com/services/employeeuserdefinedfields">
      <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>
    </FindUserDefinedFields>
  </s:Body>
</s:Envelope>

GetUserDefinedFieldsByEmployeeIdentifier

<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/employeeuserdefinedfields/IEmployeeUserDefinedFields/GetUserDefinedFieldsByEmployeeIdentifier</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">dd5937d6-13ee-4704-af36-4764e342f0cb</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">J43CW</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <GetUserDefinedFieldsByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeeuserdefinedfields">
      <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>676554345</b:EmployeeNumber> 
      </employeeIdentifier>
    </GetUserDefinedFieldsByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

UpdateUserDefinedFields

<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/employeeuserdefinedfields/IEmployeeUserDefinedFields/UpdateUserDefinedFields</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">dd5937d6-13ee-4704-af36-4764e342f0cb</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">J43CW</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <UpdateUserDefinedFields xmlns="http://www.ultipro.com/services/employeeuserdefinedfields">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:UserDefinedFields>
          <b:EecUdField01>User definition</b:EecUdField01> 
          <b:EecUdField02 i:nil="true" /> 
          <b:EecUdField03 i:nil="true" /> 
          <b:EecUdField04 i:nil="true" /> 
          <b:EecUdField05 i:nil="true" /> 
          <b:EecUdField06>0001-01-01T00:00:00</b:EecUdField06> 
          <b:EecUdField07>0001-01-01T00:00:00</b:EecUdField07> 
          <b:EecUdField08>0001-01-01T00:00:00</b:EecUdField08> 
          <b:EecUdField09>0</b:EecUdField09> 
          <b:EecUdField10>0</b:EecUdField10> 
          <b:EecUdField11 i:nil="true" /> 
          <b:EecUdField12 i:nil="true" /> 
          <b:EecUdField13 i:nil="true" /> 
          <b:EecUdField14 i:nil="true" /> 
          <b:EecUdField15 i:nil="true" /> 
          <b:EecUdField16>0001-01-01T00:00:00</b:EecUdField16> 
          <b:EecUdField17>0001-01-01T00:00:00</b:EecUdField17> 
          <b:EecUdField18>0001-01-01T00:00:00</b:EecUdField18> 
          <b:EecUdField19>0</b:EecUdField19> 
          <b:EecUdField20>0</b:EecUdField20> 
          <b:EecUdField21 i:nil="true" /> 
          <b:EecUdField22 i:nil="true" /> 
          <b:EecUdField23 i:nil="true" /> 
          <b:EecUdField24 i:nil="true" /> 
          <b:EecUdField25>0</b:EecUdField25> 
          <b:EecUdField26>0</b:EecUdField26> 
          <b:EecUdField27>0001-01-01T00:00:00</b:EecUdField27> 
          <b:EecUdField28>0001-01-01T00:00:00</b:EecUdField28> 
          <b:EecUdField29 i:nil="true" /> 
          <b:EepUdField01 i:nil="true" /> 
          <b:EepUdField02 i:nil="true" /> 
          <b:EepUdField03>0</b:EepUdField03> 
          <b:EepUdField04>0</b:EepUdField04> 
          <b:EepUdField05>0001-01-01T00:00:00</b:EepUdField05> 
          <b:EepUdField06>0001-01-01T00:00:00</b:EepUdField06> 
          <b:EepUdField07 i:nil="true" /> 
          <b:EepUdField08 i:nil="true" /> 
          <b:EepUdField09 i:nil="true" /> 
          <b:EepUdField10>0</b:EepUdField10> 
          <b:EepUdField11>0</b:EepUdField11> 
          <b:EepUdField12>0001-01-01T00:00:00</b:EepUdField12> 
          <b:EepUdField13>0001-01-01T00:00:00</b:EepUdField13> 
          <b:EepUdField14 i:nil="true" /> 
          <b:EinUdField01 i:nil="true" /> 
          <b:EinUdField02 i:nil="true" /> 
          <b:EinUdField03>0</b:EinUdField03> 
          <b:EinUdField04>0</b:EinUdField04> 
          <b:EinUdField05>0001-01-01T00:00:00</b:EinUdField05> 
          <b:EinUdField06>0001-01-01T00:00:00</b:EinUdField06> 
          <b:EinUdField07 i:nil="true" /> 
          <b:EinUdField08 i:nil="true" /> 
          <b:EinUdField09 i:nil="true" /> 
          <b:EinUdField10>0</b:EinUdField10> 
          <b:EinUdField11>0</b:EinUdField11> 
          <b:EinUdField12>0001-01-01T00:00:00</b:EinUdField12> 
          <b:EinUdField13>0001-01-01T00:00:00</b:EinUdField13> 
          <b:EinUdField14 i:nil="true" /> 
          <b:EmployeeIdentifier i:nil="true" /> 
        </b:UserDefinedFields>
      </entities>
    </UpdateUserDefinedFields>
  </s:Body>
</s:Envelope>