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

Employee Job Service API

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

Overview

This document describes the methods of the service and provides code examples using Microsoft’s Visual Studio 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.

Employee Job Object

The employee job object includes the following properties.

PropertyRequiredTypeDescription
Agricultural
BooleanIf true, selects the employee as agricultural.
AlternateTitle
StringEmployee’s alternate title.
DateInJob
DateView only. Effective date of the employee’s current job.
DirectLabor
BooleanIf true, selects the employee as direct labor.
EffectiveDateYesDateRequired for updates. The effective date of the job change.
EmployeeIdentifierYesReferenceID that represents a person.
EmployeeTypeYesCode listEmployee type code.
FullOrPartTimeYesCode list

Employee status.

F = Full time

P = Part time

HourlyOrSalariedYesCode list

Employee’s pay type.

H = Hourly

S = Salaried

JobCodeYesCode listEmployee’s job code.
JobGroup
Code listEmployee’s job group code.
LocalUnion
Code listEmployee’s local union code.
NationalUnion
Code listEmployee’s national union code.
OrgLevel1
Code listEmployee’s organizational 1 code.
OrgLevel2
Code listEmployee’s organizational 2 code.
OrgLevel3
Code listEmployee’s organizational 3 code.
OrgLevel4
Code listEmployee’s organizational 4 code.
PayFrequencyYesCode list

Pay frequency code associated with the pay group.

B = Biweekly

M = Monthly

S = Semi-monthly

W = Weekly

PayGroupYesCode listEmployee’s pay group.
Project
Code listEmployee’s project code.
Promotion
BooleanIf true, selects the job change as a promotion.
ReasonCode
Code list

Required for updates.

Reason code for the job change.

ScheduledHoursYesDecimalEmployee’s scheduled hours.
Seasonal
BooleanIf true, selects the employee as a seasonal worker.
ShiftCode
Code listEmployee’s shift code.
ShiftGroup
Code listEmployee’s shift group.
Supervisor
ReferenceID that represents a person that is the supervisor
TimeClock
StringEmployee’s time clock code.
Transfer
BooleanIf true, selects the job change as a transfer.
YouthTraining
BooleanIf true, selects the employee as youth and/or training.
PayScaleCode
StringRequired if UsePayScale=”Y”
StepNo
intRequired if UsePayScale=”Y”

Quick Start

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

FindJobs

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 recrods to return per PageNumber. You can return a maximum of 100 records per PageNumber.

GetJobByEmployeeIdentifier

This method allows you to retrieve an individual job 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 job information.
UpdateJob
This method allows you to update the job information. We recommend executing a find or get to retrieve the job 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 Job 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.

Example created service references

Example created service references

Example Code

The following code is an example of retrieving employee job 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"

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


    using ConsoleSample.EmployeeJobService;
    using ConsoleSample.LoginService;


    public class Program
    {
        internal 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;
                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:
                    FindJobs(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();
                throw;
            }
        }


        private static void FindJobs(string customerApi, string token)
        {
            const string ultiproTokenNamespace =
                "http://www.ultimatesoftware.com/foundation/authentication/ultiproToken";


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


            // Create a proxy to the job service:
            var employeeJobClient = new EmployeeJobClient("WSHttpBinding_IEmployeeJob");


            try
            {
                // Add the headers for the Customer API key and authentication token:
                using (new OperationContextScope(employeeJobClient.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 employeeQuery =
                        new EmployeeQuery
                            {
                                // Set one or more properties to search:
                                LastName = "LIKE (ba%)",
                                FullOrPartTime = "=F",


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


                    // Find jobs for employees matching the query criteria:
                    JobFindResponse jobFindResponse =
                        employeeJobClient.FindJobs(employeeQuery);


                    // Check the results of the find to see if there are any errors:
                    if (jobFindResponse.OperationResult.HasErrors)
                    {
                        // Review each error:
                        foreach (OperationMessage message in
                            jobFindResponse.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
                    else
                    {
                        // If employee records are returned, loop through the
                        // results and output example data:
                        foreach (EmployeeJob employeeJob in jobFindResponse.Results)
                        {
                            foreach (Job job in employeeJob.Jobs)
                            {
                                Console.WriteLine(
                                    "Last name: {0} Job: {1} Type: {2}",
                                    employeeJob.LastName,
                                    job.JobCode,
                                    job.EmployeeType);
                            }
                        }


                        var pagingInfo = jobFindResponse.OperationResult.PagingInfo;


                        Console.WriteLine(
                            "The employee query returned a total of {0} records.",
                            pagingInfo.TotalItems);


                        Console.WriteLine(
                            "The employee query returned a total of {0} pages.",
                            pagingInfo.PageTotal);


                        Console.WriteLine(
                            "Each page contains {0} records.",
                            pagingInfo.PageSize);


                        Console.WriteLine(
                            "The Results contain the records for page {0}.",
                            pagingInfo.CurrentPage);
                    }
                }


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

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.

FindJobs

  <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/employeejob/IEmployeeJob/FindJobs</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">e477967b-aa38-4187-a1a9-0849a8aab891</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
</s:Header>
  <s:Body>
  <FindJobs xmlns="http://www.ultimatesoftware.com/services/employeejob">
  <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>
</FindJobs>
</s:Body>
</s:Envelope>

GetJobByEmployeeIdentifier

  <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/employeejob/IEmployeeJob/GetJobByEmployeeIdentifier</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">e477967b-aa38-4187-a1a9-0849a8aab891</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
</s:Header>
  <s:Body>
  <GetJobByEmployeeIdentifier xmlns="http://www.ultimatesoftware.com/services/employeejob">
  <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>555667788</b:EmployeeNumber> 
</employeeIdentifier>
</GetJobByEmployeeIdentifier>
</s:Body>
</s:Envelope>

UpdateJobs

  <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/employeejob/IEmployeeJob/UpdateJob</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">e477967b-aa38-4187-a1a9-0849a8aab891</ultiproToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
</s:Header>
  <s:Body>
  <UpdateJob xmlns="http://www.ultimatesoftware.com/services/employeejob">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:Job>
<b:Agricultural>false</b:Agricultural> 
<b:AlternateTitle>Asssistant</b:AlternateTitle> 
<b:DateInJob>0001-01-01T00:00:00</b:DateInJob> 
<b:DirectLabor>false</b:DirectLabor> 
<b:EffectiveDate>0001-01-01T00:00:00</b:EffectiveDate> 
  <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
<b:CompanyCode i:nil="true" /> 
<b:EmployeeNumber i:nil="true" /> 
</b:EmployeeIdentifier>
<b:EmployeeType i:nil="true" /> 
<b:FullOrPartTime>Full-time</b:FullOrPartTime> 
<b:HourlyOrSalaried i:nil="true" /> 
<b:JobCode i:nil="true" /> 
<b:JobGroup i:nil="true" /> 
<b:LocalUnion i:nil="true" /> 
<b:NationalUnion i:nil="true" /> 
<b:OrgLevel1 i:nil="true" /> 
<b:OrgLevel2 i:nil="true" /> 
<b:OrgLevel3 i:nil="true" /> 
<b:OrgLevel4 i:nil="true" /> 
<b:PayFrequency i:nil="true" /> 
<b:PayGroup i:nil="true" /> 
  <b:PayScaleCode>ABC</b:PayScaleCode>
<b:Project i:nil="true" /> 
<b:Promotion>false</b:Promotion> 
<b:ReasonCode i:nil="true" /> 
<b:ScheduledHours>0</b:ScheduledHours> 
<b:Seasonal>false</b:Seasonal> 
  <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <c:KeyValueOfstringstring>
<c:Key /> 
<c:Value /> 
</c:KeyValueOfstringstring>
</b:SelfServiceProperties>
<b:ShiftCode i:nil="true" /> 
<b:ShiftGroup i:nil="true" /> 
  <b:StepNo>1</b:StepNo>
<b:Supervisor i:nil="true" /> 
<b:TimeClock i:nil="true" /> 
<b:Transfer>false</b:Transfer> 
<b:YouthTraining>false</b:YouthTraining>  
</b:Job>
</entities>
</UpdateJob>
</s:Body>
</s:Envelope>