UKG Pro Web Services API Guide

Employee Address 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 Address Service API

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

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 Address Object

The employee address object includes the following properties.


Property	Required	Type	Description
AddressLine1	Yes	String
AddressLine2		String
City	Yes	String
Country	Yes	Code list	A valid country code.
County		String
StateOrProvince	Yes	Code list	A valid UKG Pro state code.
ZipOrPostalCode	Yes	String
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 address 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 Address 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 Address Web Service.

FindAddresses

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.

GetAddressByEmployeeIdentifier

This method allows you to retrieve an individual address 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 the address information.

UpdateAddress

This method allows you to update the address information. We recommend executing a find or get to retrieve the address 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 Address 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 C# Code

The following code is an example of retrieving employee address 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.EmployeeAddressService;
    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 employee addresses:
                    FindAddresses(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 FindAddresses(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 address service:
            var employeeAddressClient = new EmployeeAddressClient("WSHttpBinding_IEmployeeAddress");

            try
            {
                // Add the headers for the Customer API key and authentication token:
                using (new OperationContextScope(employeeAddressClient.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 addresses for employees matching the query criteria:
                    AddressFindResponse addressFindResponse =
                        employeeAddressClient.FindAddresses(employeeQuery);

                    // Check the results of the find to see if there are any errors:
                    if (addressFindResponse.OperationResult.HasErrors)
                    {
                        // Review each error:
                        foreach (OperationMessage message in
                            addressFindResponse.OperationResult.Messages)
                        {
                            Console.WriteLine("Error message: " + message.Message);
                        }
                    }
                    else
                    {
                        // If employee records are returned, loop through the
                        // results and output example data:
                        foreach (EmployeeAddress employeeAddress in
                            addressFindResponse.Results)
                        {
                            foreach (Address address in employeeAddress.Addresses)
                            {
                                Console.WriteLine(
                                    "Last name: {0} Address: {1} City: {2}",
                                    employeeAddress.LastName,
                                    address.AddressLine1,
                                    address.City);
                            }
                        }

                        var pagingInfo = addressFindResponse.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);
                    }
                }

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

XML Examples

The Authentication Service (http://<address>/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.

FindAddresses

<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/employeeaddress/IEmployeeAddress/FindAddresses</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>
    <FindAddresses xmlns="http://www.ultipro.com/services/employeeaddress">
      <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>
    </FindAddresses>
  </s:Body>
</s:Envelope>

GetAddressByEmployeeIdentifier

<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/employeeaddress/IEmployeeAddress/GetAddressByEmployeeIdentifier</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>
    <GetAddressByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeeaddress">
      <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>
    </GetAddressByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

UpdateAddress

<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/employeeaddress/IEmployeeAddress/UpdateAddress</a:Action> 
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">e0ceac80-baf5-4abf-9b87-89628c931c71</UltiProToken> 
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey> 
  </s:Header>
  <s:Body>
    <UpdateAddress xmlns="http://www.ultipro.com/services/employeeaddress">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:Address>
          <b:AddressLine1>207 Champions Way</b:AddressLine1> 
          <b:AddressLine2 i:nil="true" /> 
          <b:City>Laurel</b:City> 
          <b:Country>USA</b:Country> 
          <b:County i:nil="true" /> 
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode>C0014</b:CompanyCode> 
            <b:EmployeeNumber>555667788</b:EmployeeNumber> 
          </b:EmployeeIdentifier>
          <b:SelfServiceProperties xmlns:c="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <c:KeyValueOfstringstring>
              <c:Key /> 
              <c:Value /> 
            </c:KeyValueOfstringstring>
          </b:SelfServiceProperties>
          <b:StateOrProvince>MD</b:StateOrProvince> 
          <b:ZipOrPostalCode>20723</b:ZipOrPostalCode> 
        </b:Address>
      </entities>
    </UpdateAddress>
  </s:Body>
</s:Envelope>

© UKG Inc. All rights reserved. For a full list of UKG trademarks, visit www.ukg.com/trademarks. All other trademarks, if any, are the property of their respective owners. No part of this document or its content may be reproduced in any form or by any means or stored in a database or retrieval system without the prior written authorization of UKG Inc. (“UKG”). Information in this document is subject to change without notice. The document and its content are confidential information of UKG and may not be disseminated to any third party. Nothing herein constitutes legal advice, tax advice, or any other advice. All legal or tax questions or concerns should be directed to your legal counsel or tax consultant.

Liability/Disclaimer

UKG makes no representation or warranties with respect to the accuracy or completeness of the document or its content and specifically disclaims any responsibility or representation for other vendors’ software. The terms and conditions of your agreement with us regarding the software or services provided by us, which is the subject of the documentation contained herein, govern this document or content. All company, organization, person, and event references are fictional. Any resemblance to actual companies, organizations, persons, and events is entirely coincidental.

Links to Other Materials: The linked sites and embedded links are not under the control of UKG. We reserve the right to terminate any link or linking program at any time. UKG does not endorse companies or products to which it links. If you decide to access any of the third-party sites linked to the site, you do so entirely at your own risk.