UKG Pro Web Services API Guide

Federated Single Sign-on User Service

UKG Pro Federated SSO User Service API

The UKG Pro Federated SSO User Service API enables the user to programmatically retrieve and update employee SSO User 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 2010 using C#.

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	UKG Pro Web User or UKG Pro Site Admin with API keys

Federated SSO User Object

The Federated SSO User object includes the following properties.


Property	Required	Type	Description
ActivationKey		Guid	A unique key used during manual provisioning. It is automatically generated on create.
ClientUserName	Yes	String	Employee’s network identity account used for federation.
EmployeeIdentifier	Yes	Reference	ID that represents a person. This is a reference object of the type of identifier you are using. Valid identifiers are: EmployeeNumberIdentifier EmailAddressIdentifier SsnIdentifier SinIdentifier (For Canada) NationalIdentifier (Global person identifier)
RetryAttempts		Int	Number of times a user has failed manual provisioning. Defaults to 0 on create.
Status		Int	Defaults to 0 on create which is not an active user. In most cases you’ll want to use 1 to set the users as active. 0 = Provisional (Used during manual provisioning) 1 = Complete 2 = Failed
UltiProUserName		String	The UKG Pro web user account. If not passed in, the service will look up the account based on the employee identifier.

Quick Start

This section provides steps for creating a sample application in your development environment to retrieve and update the Federated SSO User information.

Prerequisites

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

UKG Pro web user account and password
User API key and Customer API key from the UKG Pro web service administrative page

Methods

This section introduces the API methods for the Federated SSO User Web Service.

FindSSOUsers

This method provides a way to query the web service based on one or more filter criteria.

Syntax

Binding.FindSSOUsers(EmployeeQuery)

Code Example

// Find employees
EmployeeQuery query = new EmployeeQuery();
query.LastName = "LIKE (a%)";

SsoUserFindResponse findresponse = SsoUserClient.FindSsoUsers(query);

// Check the results of the find to see if there are any errors.
if (findresponse.OperationResult.HasErrors)
{
    // Review each error.
    foreach (OperationMessage message in findresponse.OperationResult.Messages)
    {
        Console.WriteLine("Error message: " + message.Message);
    }
}
else
{
    // If employee records are returned, loop through the results
    // and write out the data.
    foreach (EmployeeSsoUser employeessouser in findresponse.Results)
    {
        // If null, it's not an employee setup for SSO
        if (employeessouser.SsoUsers != null)
        {
            foreach (SsoUser ssouser in employeessouser.SsoUsers)
            {
                Console.WriteLine("Last name:" + employeessouser.LastName + ", UltiPro user:" + ssouser.UltiProUserName);
            }
        }
    }
}

GetSSOUserByEmployeeIdentifier

This method allows you to retrieve an individual SSO user record by providing an employee identifier.

This is helpful when 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 SSO user information.

Syntax: Binding.GetSSOUserByEmployeeIdentifier(employeeIdentifier)
Code Example: Refer to the quick start code for an example.

GetSSOUserByClientUserName

This method allows you to retrieve an individual SSO user record by providing the client user name. The client user name is the ID that is sent to UltiPro during the authentication process. This is helpful when you do not know the UltiPro web user name.

Syntax: Binding.GetSSOUserByClientUserName(clientusername)
Code Example: Refer to the quick start code for an example.

CreateSSOUser

This method allows you to create a new SSO user record.

Syntax: Binding.CreateSSOUser(SSOUser[])
Code Example: Refer to the quick start code for an example.

UpdateSSOUser

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

Syntax: Binding.UpdateSSOUser(SSOUser[])
Code Example: Refer to the quick start code for an example.

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 Federated SSO User 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 Code

The following code is an example of retrieving and updating Federated SSO User 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.

UserName = "YOUR 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.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using SsoUserServiceClient.LoginService;
using SsoUserServiceClient.SsoUserService;

namespace SsoUserServiceClient
{
    class Program
    {
        // Service addresses:
        private const string LoginServiceAddress = "http://[ENTER URL]/services/LoginService";
        private const string SsoUserServiceAddress = "http://[ENTER URL]/services/EmployeeSsoUser";

        // Noble user credentials:
        private const string CustomerAPIkey = "";
        private const string UserAPIkey = "";
        private const string UserName = "";
        private const string Password = "";

        private const string SsoUserUltiProUserName = "AllieC";

        // The EmployeeIdentifier identifies the employee user for whom we are creating an SsoUser record.
        private static readonly EmployeeNumberIdentifier SsoUserEmployeeIdentifier =
                                    new EmployeeNumberIdentifier()
                                    {
                                        EmployeeNumber = "735070809"
                                    };

        private static readonly EmployeeSsoUserClient SsoUserClient =
                new EmployeeSsoUserClient("WSHttpBinding_IEmployeeSsoUser", SsoUserServiceAddress);

        private static readonly LoginServiceClient LoginServiceClient =
                new LoginServiceClient("WSHttpBinding_ILoginService", LoginServiceAddress);

        static void Main(string[] args)
        {
            // Acquire an UltiPro security token for the given user credentials.
            string token = Authenticate();
            Console.WriteLine("Authentication successful.");

            // Here, we create a new, populated instance of an SsoUser.
            // This will be used to demonstrate the EmployeeSsoUser CRUD operations.
            SsoUser user = CreateNewSsoUser();
            Console.WriteLine("New user object populated");

            // The OperationContextScope allows us to set the outgoing SOAP header
            using (var scope = new OperationContextScope((IContextChannel)SsoUserClient.InnerChannel))
            {
                SetHeaders(token);

                // We can not create an existing record, so clear it out if needed for the subsequent demonstration.
                //ResetSsoUserData();

                // Create an SsoUser record:
                SsoUserCreateResponse createResponse = SsoUserClient.CreateSsoUser(new[] { user });
                Assert.IsTrue(createResponse.Success);
                Console.WriteLine("Created Federated SSO User for " + user.ClientUserName);

                // Get the new SsoUser record (here we demostrate GetSsoUserByClientUserName):
                user = SsoUserClient.GetSsoUserByClientUserName("MyClientUserName").Results.First();
                Assert.AreEqual("MyClientUserName", user.ClientUserName);
                Assert.AreEqual(SsoUserUltiProUserName, user.UltiProUserName);
                Assert.AreEqual(5, user.RetryAttempts); // We will be updating this field.
                Console.WriteLine("Retrieved Federated SSO for UltiPro user " + user.UltiProUserName);

                // Update the RetryAttempts on the new SsoUser record:
                Console.WriteLine("Updating retry attemps. Current value: " + user.RetryAttempts.ToString());
                user.RetryAttempts = 0;
                SsoUserUpdateResponse updateResponse = SsoUserClient.UpdateSsoUser(new[] { user });
                Assert.IsTrue(updateResponse.Success);

                // Get the modified SsoUser record (here we demostrate GetSsoUserByEmployeeIdentifier):
                user = SsoUserClient.GetSsoUserByEmployeeIdentifier(SsoUserEmployeeIdentifier).Results.First();
                Assert.AreEqual(SsoUserEmployeeIdentifier.EmployeeNumber, ((EmployeeNumberIdentifier)user.EmployeeIdentifier).EmployeeNumber);
                Assert.AreEqual(0, user.RetryAttempts);
                Console.WriteLine("Updatd retry attempts to value: " + user.RetryAttempts);

                // Delete the new SsoUser record:
                // Here we leverage the convenience of an already populated SsoUser object; however,
                // the minimum data required for a delete is ClientUserName + EmployeeIdentifier.
                SsoUserDeleteResponse deleteResponse = SsoUserClient.DeleteSsoUser(new[] { user });
                Assert.IsTrue(deleteResponse.Success);

                // Verify that the new SsoUser record was deleted:
                Assert.IsTrue(SsoUserClient.GetSsoUserByClientUserName("MyClientUserName").Results.Count() == 0);
                Console.WriteLine("Deleted user...Press a key to exit.");
                Console.ReadKey();
            }
        }

        private static void ResetSsoUserData()
        {
            var results = SsoUserClient.GetSsoUserByEmployeeIdentifier(SsoUserEmployeeIdentifier).Results;
            
            if (results != null)
            {
                SsoUserDeleteResponse deleteResponse = SsoUserClient.DeleteSsoUser(new[] { results.FirstOrDefault() });
            }
        }

        private static SsoUser CreateNewSsoUser()
        {
            var user =
                new SsoUser()
                {
                    ClientUserName = "MyClientUserName",
                    EmployeeIdentifier = SsoUserEmployeeIdentifier,
                    RetryAttempts = 5,
                    Status = 1 // When Status = 1, the service will lookup and populate the corresponding UltiPro user name.
                };

            return user;
        }

        /// <summary>
        /// Sets the outgoing SOAP headers.
        /// UltiProToken and CustomerAPIkey are required, with the correct namespaces.
        /// </summary>
        /// <param name="token">A valid UltiPro security token</param>
        private static void SetHeaders(string token)
        {
            MessageHeaders headers = OperationContext.Current.OutgoingMessageHeaders;

            headers.Add(MessageHeader.CreateHeader("UltiProToken", "http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken", token));
            headers.Add(MessageHeader.CreateHeader("ClientAccessKey", "http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey", CustomerAPIkey));
        }

        /// <summary>
        /// Calls the LoginService to provide a token for the given user credentials.
        /// The CustomerAPIkey and UserAPIkey for the given user may be obtained from UltiPro Web.
        /// </summary>
        /// <returns>A valid UltiPro security token</returns>
        private static string Authenticate()
        {
            string statusMessage;
            string token;

            LoginServiceClient.Authenticate(CustomerAPIkey, Password, UserAPIkey, UserName, out statusMessage, out token);

            // If authentication succeeded, statusMessage will be null
            Assert.IsNull(statusMessage);

            // If authentication succeeded, the token should be a GUID
            Guid result;
            Assert.IsTrue(Guid.TryParse(token, out result));

            return token;
        }
    }
}


// Example Quick Start Code End

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.

FindSSOUsers

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/FindSsoUsers</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <FindSsoUsers xmlns="http://www.ultipro.com/services/employeessouser">
      <query xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:CompanyCode i:nil="true"/>
        <b:CompanyName i:nil="true"/>
        <b:Country i:nil="true"/>
        <b:EmployeeNumber i:nil="true"/>
        <b:FirstName>like (a%)</b:FirstName> 
        <b:FormerName i:nil="true"/>
        <b:FullOrPartTime i:nil="true"/>
        <b:Job i:nil="true"/>
        <b:LastHire i:nil="true"/>
        <b:LastName i:nil="true"/>
        <b:Location i:nil="true"/>
        <b:OrganizationLevel1 i:nil="true"/>
        <b:OrganizationLevel2 i:nil="true"/>
        <b:OrganizationLevel3 i:nil="true"/>
        <b:OrganizationLevel4 i:nil="true"/>
        <b:OriginalHire i:nil="true"/>
        <b:PageNumber i:nil="true"/>
        <b:PageSize i:nil="true"/>
        <b:PayGroup i:nil="true"/>
        <b:Status i:nil="true"/>
        <b:SupervisorLastName i:nil="true"/>
        <b:TerminationDate i:nil="true"/>
        <b:TimeClockId i:nil="true"/>
      </query>
    </FindSsoUsers>
  </s:Body>
</s:Envelope>

GetSSOUserByEmployeeIdentifier

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/GetSsoUserByEmployeeIdentifier</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <GetSsoUserByEmployeeIdentifier xmlns="http://www.ultipro.com/services/employeessouser">
      <employeeIdentifier i:type="b:EmployeeNumberIdentifier" xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:CompanyCode i:nil="true"/>
        <b:EmployeeNumber>735070809</b:EmployeeNumber>
      </employeeIdentifier>
    </GetSsoUserByEmployeeIdentifier>
  </s:Body>
</s:Envelope>

GetSSOUserByClientUserName

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/GetSsoUserByClientUserName</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <GetSsoUserByClientUserName xmlns="http://www.ultipro.com/services/employeessouser">
      <clientUserName>MyClientUserName</clientUserName>
    </GetSsoUserByClientUserName>
  </s:Body>
</s:Envelope>

CreateSSOUser

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/CreateSsoUser</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <CreateSsoUser xmlns="http://www.ultipro.com/services/employeessouser">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:SsoUser>
          <b:ActivationKey>00000000-0000-0000-0000-000000000000</b:ActivationKey>
          <b:ClientUserName>MyClientUserName</b:ClientUserName>
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
            <b:CompanyCode i:nil="true"/>
            <b:EmployeeNumber>735070809</b:EmployeeNumber>
          </b:EmployeeIdentifier>
          <b:RetryAttempts>5</b:RetryAttempts>
          <b:Status>1</b:Status>
          <b:UltiProUserName i:nil="true"/>
        </b:SsoUser>
      </entities>
    </CreateSsoUser>
  </s:Body>
</s:Envelope>

UpdateSSOUser

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/UpdateSsoUser</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <UpdateSsoUser xmlns="http://www.ultipro.com/services/employeessouser">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:SsoUser>
          <b:ActivationKey>00000000-0000-0000-0000-000000000000</b:ActivationKey>
          <b:ClientUserName>MyClientUserName</b:ClientUserName>
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
          <b:CompanyCode i:nil="true"/>
          <b:EmployeeNumber>735070809</b:EmployeeNumber>
          </b:EmployeeIdentifier>
          <b:RetryAttempts>0</b:RetryAttempts>
          <b:Status>1</b:Status>
          <b:UltiProUserName i:nil="true"/>
        </b:SsoUser>
      </entities>
    </UpdateSsoUser>
  </s:Body>
</s:Envelope>

DeleteSSOUser

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://www.ultipro.com/services/employeessouser/IEmployeeSsoUser/DeleteSsoUser</a:Action>
    <UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">7ffdbe24-c89f-4d09-b92a-ead6e956f40c</UltiProToken>
    <ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">CAN12</ClientAccessKey>
    <a:To s:mustUnderstand="1">https://servicet.ultipro.com/services/EmployeeSsoUser</a:To>
  </s:Header>
  <s:Body>
    <DeleteSsoUser xmlns="http://www.ultipro.com/services/employeessouser">
      <entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <b:SsoUser>
          <b:ActivationKey>00000000-0000-0000-0000-000000000000</b:ActivationKey>
          <b:ClientUserName>MyClientUserName</b:ClientUserName>
          <b:EmployeeIdentifier i:type="b:EmployeeNumberIdentifier">
          <b:CompanyCode i:nil="true"/>
          <b:EmployeeNumber>735070809</b:EmployeeNumber>
          </b:EmployeeIdentifier>
          <b:RetryAttempts>5</b:RetryAttempts>
          <b:Status>1</b:Status>
          <b:UltiProUserName i:nil="true"/>
        </b:SsoUser>
      </entities>
    </DeleteSsoUser>
  </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.