Development Opportunity Session Service
UKG Pro Web Services API Guide
Development Opportunity Session Service
Introduction
With UKG’s 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.
Development Opportunity Session Service API
The UKG Pro Development Opportunity Session Service API enables the user to programmatically retrieve and update Development Opportunity Session information in UKG Pro.
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).
Development Opportunity Session Object
The Development Opportunity Session object includes the following properties:
Property | Type | Length |
---|---|---|
SessionId | Int | |
IntegrationId | String | |
OpportunityId | Int | |
Provider | String | 10 |
StartDateTime | Datetime | |
Required | ||
Cannot be > EndDateTime | ||
Cannot be deleted if there is an associated participation record | ||
EndDateTime | Datetime | |
Instructor | String | 255 |
Facility | String | 255 |
Cost | Decimal | |
CreatedBy | EmployeeIdentifier | |
UpdatedBy | EmployeeIdentifier |
Quick Start
This section provides steps for creating a sample application in your development environment to retrieve and update the Development Opportunity Session 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 Development Opportunity 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 Development Opportunity Web Service.
- GetSession: This method will be used to query by
OpportunityId
andIntegrationId
for a session that has already been created in UKG Pro. The entire Session object is returned. - GetSessionId: This helper method will be used to query by
OpportunityId
andIntegrationId
for a session that has already been created in UKG Pro. Only theSessionId
is returned. - CreateSession: This method will be used to add a new development opportunity session.
- UpdateSession: The method provides a way to update an existing development opportunity session.
- DeleteSession: The method provides a way to delete a development opportunity session. Please note it is necessary to delete all participation records for a session before deleting the session.
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 DevelopmentOpportunitySession 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 Development Opportunity Session 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 CareerDevelopmentApiGuides
{
using System;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Channels;
using DevelopmentOpportunitySession;
using Login;
using EmailAddressIdentifier = DevelopmentOpportunitySession.EmailAddressIdentifier;
using OperationMessage = DevelopmentOpportunitySession.OperationMessage;
using Result = DevelopmentOpportunitySession.Result;
class Program
{
static void Main(string[] args)
{
// Create a proxy to the login service.
LoginServiceClient loginClient = new LoginServiceClient("WSHttpBinding_ILoginService");
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.");
// Create Session
CreateSession(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);
}
}
private static void CreateSession(string customerApiKey,
string authenticationToken)
{
// Create a proxy to the development opportunity session service.
DevelopmentOpportunitySessionClient proxySession =
new DevelopmentOpportunitySessionClient("WSHttpBinding_IDevelopmentOpportunitySession");
try
{
// Add the headers for the Customer API key and authentication token.
using (new OperationContextScope(proxySession.InnerChannel))
{
OperationContext.Current.OutgoingMessageHeaders
.Add(MessageHeader.CreateHeader("UltiProToken",
"http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken",
authenticationToken));
OperationContext.Current.OutgoingMessageHeaders
.Add(MessageHeader.CreateHeader("ClientAccessKey",
"http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey",
customerApiKey));
// Define for which opportunity you would like to create a session.
int opportunityId = 36;
// Create a session.
DevelopmentOpportunitySession.DevelopmentOpportunitySession newSession =
new DevelopmentOpportunitySession.
DevelopmentOpportunitySession()
{
OpportunityId = opportunityId,
IntegrationId = Guid.NewGuid().ToString(),
StartDateTime = new DateTime(2012, 6, 18),
EndDateTime = new DateTime(2012, 9, 18),
CreatedBy = new EmailAddressIdentifier
{ EmailAddress = "[email protected]" },
Instructor = "Mr. Jones",
Cost = 65.00m,
};
// Submit the create.
DevelopmentOpportunitySessionCreateResponse response =
proxySession.CreateSession( new[] { newSession });
// Check for errors.
if (response.HasErrors)
{
if (response.OperationResult.HasErrors)
{
// Review each operation error.
foreach (OperationMessage message in response.OperationResult.Messages)
{
Console.WriteLine("Operation Error Message: " + message.Message);
}
}
// Review result errors.
foreach (Result result in response.Results.Where(r => r.HasErrors))
{
// Review each error for this result.
foreach (OperationMessage message in result.Messages)
{
Console.WriteLine("Result " + result.RequestNumber
+ " Error Message: " + message.Message);
}
}
}
else
{
// The create was successful.
Console.WriteLine("Create successful.");
}
}
proxySession.Close();
}
catch (Exception ex)
{
proxySession.Abort();
Console.WriteLine("Exception:" + ex);
}
}
// Additional methods: GetSession, GetSessionId, UpdateSession, DeleteSession
}
}
// 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.GetSessionByOpportunityIdIntegrationId
<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/developmentopportunitysession/IDevelopmentOpportunitySession/GetSessionByOpportunityIdIntegrationId</a:Action>
<UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2956e54f-0eb5-42e2-a654-57028059caf7</UltiProToken>
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey>
</s:Header>
<s:Body>
<GetSessionByOpportunityIdIntegrationId xmlns="http://www.ultipro.com/services/developmentopportunitysession">
<opportunityId>1234</opportunityId>
<integrationId>1001</integrationId>
</GetSessionByOpportunityIdIntegrationId>
</s:Body>
</s:Envelope>
GetSessionIdByOpportunityIdIntegrationId
<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/developmentopportunitysession/IDevelopmentOpportunitySession/GetSessionIdByOpportunityIdIntegrationId</a:Action>
<UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2956e54f-0eb5-42e2-a654-57028059caf7</UltiProToken>
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey>
</s:Header>
<s:Body>
<GetSessionIdByOpportunityIdIntegrationId xmlns="http://www.ultipro.com/services/developmentopportunitysession">
<opportunityId>1234</opportunityId>
<integrationId>1001</integrationId>
</GetSessionIdByOpportunityIdIntegrationId>
</s:Body>
</s:Envelope>
CreateSession
<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/developmentopportunitysession/IDevelopmentOpportunitySession/CreateSession</a:Action>
<UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2956e54f-0eb5-42e2-a654-57028059caf7</UltiProToken>
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey>
</s:Header>
<s:Body>
<CreateSession xmlns="http://www.ultipro.com/services/developmentopportunitysession">
<entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<b:DevelopmentOpportunitySession>
<b:Cost>500</b:Cost>
<b:CreatedBy i:nil="true" />
<b:EndDateTime>2013-12-31T00:00:00</b:EndDateTime>
<b:Facility>Training Room</b:Facility>
<b:Instructor />
<b:IntegrationId>1001</b:IntegrationId>
<b:OpportunityId>1234</b:OpportunityId>
<b:Provider i:nil="true" />
<b:SessionId>1357</b:SessionId>
<b:StartDateTime>2013-04-01T00:00:00</b:StartDateTime>
<b:UpdatedBy i:nil="true" />
</b:DevelopmentOpportunitySession>
</entities>
</CreateSession>
</s:Body>
</s:Envelope>
UpdateSession
<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/developmentopportunitysession/IDevelopmentOpportunitySession/UpdateSession</a:Action>
<UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2956e54f-0eb5-42e2-a654-57028059caf7</UltiProToken>
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey>
</s:Header>
<s:Body>
<UpdateSession xmlns="http://www.ultipro.com/services/developmentopportunitysession">
<entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<b:DevelopmentOpportunitySession>
<b:Cost>500</b:Cost>
<b:CreatedBy i:nil="true" />
<b:EndDateTime>2013-04-30T00:00:00</b:EndDateTime>
<b:Facility>Training Room</b:Facility>
<b:Instructor i:nil="true" />
<b:IntegrationId>1001</b:IntegrationId>
<b:OpportunityId>1234</b:OpportunityId>
<b:Provider i:nil="true" />
<b:SessionId>1357</b:SessionId>
<b:StartDateTime>2013-04-01T00:00:00</b:StartDateTime>
<b:UpdatedBy i:nil="true" />
</b:DevelopmentOpportunitySession>
</entities>
</UpdateSession>
</s:Body>
</s:Envelope>
DeleteSession
<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/developmentopportunitysession/IDevelopmentOpportunitySession/DeleteSession</a:Action>
<UltiProToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiprotoken">2956e54f-0eb5-42e2-a654-57028059caf7</UltiProToken>
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey>
</s:Header>
<s:Body>
<DeleteSession xmlns="http://www.ultipro.com/services/developmentopportunitysession">
<entities xmlns:b="http://www.ultipro.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<b:DevelopmentOpportunitySession>
<b:Cost>0</b:Cost>
<b:CreatedBy i:nil="true" />
<b:EndDateTime>2013-04-30T00:00:00</b:EndDateTime>
<b:Facility>Training Room</b:Facility>
<b:Instructor i:nil="true" />
<b:IntegrationId>1001</b:IntegrationId>
<b:OpportunityId>1234</b:OpportunityId>
<b:Provider i:nil="true" />
<b:SessionId>1357</b:SessionId>
<b:StartDateTime>2013-04-01T00:00:00</b:StartDateTime>
<b:UpdatedBy i:nil="true" />
</b:DevelopmentOpportunitySession>
</entities>
</DeleteSession>
</s:Body>
</s:Envelope>
Updated 17 days ago