Employee Person Service
UKG Pro Web Services API Guide
Employee Person Service
Employee Person Service API
The UKG Pro Employee Person Service API enables the user to programmatically retrieve and update employee person 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 with 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 Person Object
The employee person object includes the following properties:
Property | Required | Type | Description |
---|---|---|---|
AlternateEmailAddress | String | Alternate email address. | |
EmailAddress | String | Primary email address. | |
FirstName | Yes | String | First name of the person. |
FormerLastName | String | Former last name of the person. | |
LastName | Yes | String | Last name of the person. |
MiddleName | String | Middle name of the person. | |
PreferredFirstName | String | Preferred name of the person. | |
Prefix | Code | A valid UKG Pro prefix code. | |
SSN | String | Social Security Number. | |
Suffix | Code | A valid UKG Pro suffix code. | |
SuppressSSN | Boolean | Determines if the SSN should be suppressed in the UKG Pro portal. | |
EmployeeIdentifier | Yes | Identifier | 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 person 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 Person 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 Person Web Service.
FindPeople
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
.
GetPersonByEmployeeIdentifier
This method allows you to retrieve an individual person 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 person information.
UpdatePerson
This method allows you to update the person information. We recommend executing a find or get to retrieve the person 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 Person 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
Example Code
The following code is an example of retrieving employee person 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
using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Text;
using ConsolePerson.LoginService;
using ConsolePerson.PersonService;
namespace ConsolePerson
{
class Program
{
static void Main(string[] args)
{
LoginServiceClient loginClient = null;
try
{
// Setup your user credentials.
string UserName = "";
string Password = "";
string UserAPIkey = "";
string CustomerAPIkey = "";
string Message = "";
string AuthenticationToken = "";
// Create a proxy to the login service.
loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");
// 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 employees
FindPerson(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)
{
loginClient.Abort();
Console.WriteLine("Exception:" + ex);
}
}
static void FindPerson(string CustomerAPI, string Token)
{
// Create a proxy to the person service.
EmployeePersonClient proxyPerson =
new EmployeePersonClient("WSHttpBinding_IEmployeePerson");
try
{
// Add the headers for the Customer API key and authentication token.
using (new OperationContextScope(proxyPerson.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", CustomerAPI));
// Create a query object to find the employees.
EmployeeQuery pQuery = new EmployeeQuery();
// Set one or more properties to search.
pQuery.LastName = "LIKE (ba%)";
pQuery.FullOrPartTime = "=F";
// Set paging properties
pQuery.PageSize = 10;
pQuery.PageNumber = 1;
// Search for the employees.
PersonFindResponse response = proxyPerson.FindPeople(pQuery);
// 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 (EmployeePerson employee in employees)
{
foreach (Person person in employee.People)
{
Console.WriteLine("Name:" + person.LastName + "," +
person.FirstName);
}
}
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 + ".");
}
}
proxyPerson.Close();
}
catch (Exception ex)
{
proxyPerson.Abort();
Console.WriteLine("Exception:" + ex);
}
}
}
}
// 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.FindPerson
<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/employeeperson/IEmployeePerson/FindPeople</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>
<FindPeople xmlns="http://www.ultipro.com/services/employeeperson">
<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>
</FindPeople>
</s:Body>
</s:Envelope>
GetPersonByEmployeeIdentifier
<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/employeeperson/IEmployeePerson/GetPersonByEmployeeIdentifier</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>
<GetPersonByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeeperson">
<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>
</GetPersonByEmployeeIdentifier>
</s:Body>
</s:Envelope>
UpdatePerson
<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/employeeperson/IEmployeePerson/UpdatePerson</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>
<UpdatePerson xmlns="http://www.ultipro.com/services/employeeperson">
<entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<b:Person>
<b:AlternateEmailAddress>myemail@genericemail.com</b:AlternateEmailAddress>
<b:EmailAddress i:nil="true" />
<b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
<b:CompanyCode>C0014</b:CompanyCode>
<b:EmployeeNumber>555667788</b:EmployeeNumber>
</b:EmployeeIdentifier>
<b:FirstName i:nil="true" />
<b:FormerLastName i:nil="true" />
<b:LastName i:nil="true" />
<b:MiddleName i:nil="true" />
<b:PreferredFirstName>Buffy</b:PreferredFirstName>
<b:Prefix i:nil="true" />
<b:SSN i:nil="true" />
<b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<c:KeyValueOfstringstring>
<c:Key />
<c:Value />
</c:KeyValueOfstringstring>
</b:SelfServiceProperties>
<b:Suffix i:nil="true" />
<b:SuppressSSN>false</b:SuppressSSN>
</b:Person>
</entities>
</UpdatePerson>
</s:Body>
</s:Envelope>
Updated 3 months ago