Development Opportunity Service

Development Opportunity Object

The Development Opportunity object includes the following properties.

PropertyTypeLength
OpportunityIdInt
ApplicationIdInt
TitleString*required100
DescriptionString*required1500
Course CodeString(Alphanumeric only, if set)25
CategoryString(Must be a valid UKG Pro category, if set)6
Delivery MethodStringComputer-based = CInstructor-led = ILLVideo = VWeb-based = W25
LicenseString(Must be a valid UKG Pro License, if set)6
ProviderString10
Continuing Education UnitDecimal0 - 9999999.99
CostDecimal
IntegrationIdString
ActiveBoolean
URLString200
CreatedByEmployeeIdentifier
UpdatedByEmployeeIdentifier

Quick Start

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

GetOpportunityByIntegrationId

This method will be used to query by IntegrationId for an opportunity that has already created in UKG Pro. The entire Development Opportunity object is returned.

GetOpportunityIdByIntegrationId

This helper method will be used to query by IntegrationId for an opportunity that has already been created in UKG Pro. Only the OpportunityId is returned.

CreateOpportunity

This method will be used to add a new development opportunity.

UpdateOpportunity

The method provides a way to update an existing development opportunity.

DeleteOpportunity

The method provides a way to delete a development opportunity. Please note, it is necessary to delete all participation records for all sessions, and then delete all sessions before deleting the opportunity.

C# Example

Generate the Service Reference

Once you have a user and API keys, you need to create a service reference to the DevelopmentOpportunity 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.

Example Code

The following code is an example of retrieving Development Opportunity 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 DevelopmentOpportunity;
    using Login;


    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.");


                    // Create Opportunity
                    CreateOpportunity(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 CreateOpportunity(string customerApiKey, 
            string authenticationToken)
        {
            // Create a proxy to the development opportunity service.
            DevelopmentOpportunityClient proxyOpportunity = 
                new DevelopmentOpportunityClient("WSHttpBinding_IDevelopmentOpportunity");


            try
            {
                


                // Add the headers for the Customer API key and authentication token.
                using (new OperationContextScope(proxyOpportunity.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));


                    // Create an opportunity.
                    DevelopmentOpportunity.DevelopmentOpportunity newOpportunity = 
                        new DevelopmentOpportunity.
                            DevelopmentOpportunity()
                            {
                                IntegrationId = Guid.NewGuid().ToString(),
                                Title = "Quick and Easy Cooking",
                                Description = "Simple recipes for everyday cooking",
                                CourseCode = "QEC101",
                                Cost = 85.00m,
                                Active = true,
                                CreatedBy = new EmailAddressIdentifier 
                                    { EmailAddress = "[email protected]" },
                            };


                    // Submit the create.
                    DevelopmentOpportunityCreateResponse response = 
                        proxyOpportunity.CreateOpportunity(new[] { newOpportunity });


                    // 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.");
                    }
                }
                proxyOpportunity.Close();
            }
            catch (Exception ex)
            {
                proxyOpportunity.Abort();
                Console.WriteLine("Exception:" + ex);
            }
        }
    }
}

// Example Quick Start Code End

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.

CreateOpportunity


<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/developmentopportunity/IDevelopmentOpportunity/CreateOpportunity</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2956e54f-0eb5-42e2-a654-57028059caf7</UKGProToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
</s:Header>
  <s:Body>
  <CreateOpportunity xmlns="http://www.ultimatesoftware.com/services/developmentopportunity">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:DevelopmentOpportunity>
<b:Active>true</b:Active>
  <b:ApplicationId>10</b:ApplicationId>
<b:Category i:nil="true" /> 
<b:ContinuingEducationUnit>0</b:ContinuingEducationUnit> 
<b:Cost>0</b:Cost> 
<b:CourseCode>101</b:CourseCode> 
<b:CreatedBy i:nil="true" /> 
<b:DeliveryMethod>W</b:DeliveryMethod> 
<b:Description>Test course description</b:Description> 
<b:IntegrationId>1001</b:IntegrationId> 
<b:License i:nil="true" /> 
<b:OpportunityId>0</b:OpportunityId> 
<b:Provider i:nil="true" /> 
<b:Title>Test course</b:Title> 
<b:URL>http://sample.ultmatesoftware.com</b:URL> 
<b:UpdatedBy i:nil="true" /> 
</b:DevelopmentOpportunity>
</entities>
</CreateOpportunity>
</s:Body>
</s:Envelope>

UpdateOpportunity


  <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/developmentopportunity/IDevelopmentOpportunity/UpdateOpportunity</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2956e54f-0eb5-42e2-a654-57028059caf7</UKGProToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
</s:Header>
  <s:Body>
  <UpdateOpportunity xmlns="http://www.ultimatesoftware.com/services/developmentopportunity">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:DevelopmentOpportunity>
<b:Active>true</b:Active>
  <b:ApplicationId>10</b:ApplicationId>
<b:Category i:nil="true" /> 
<b:ContinuingEducationUnit>0</b:ContinuingEducationUnit> 
<b:Cost>500</b:Cost> 
<b:CourseCode i:nil="true" /> 
<b:CreatedBy i:nil="true" /> 
<b:DeliveryMethod>W</b:DeliveryMethod> 
<b:Description i:nil="true" /> 
<b:IntegrationId>1001</b:IntegrationId> 
<b:License i:nil="true" /> 
<b:OpportunityId>0</b:OpportunityId> 
<b:Provider i:nil="true" /> 
<b:Title>Test course update</b:Title> 
<b:URL>http://sample.ultmatesoftware.com</b:URL> 
<b:UpdatedBy i:nil="true" /> 
</b:DevelopmentOpportunity>
</entities>
</UpdateOpportunity>
</s:Body>
</s:Envelope>

DeleteOpportunity


  <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/developmentopportunity/IDevelopmentOpportunity/DeleteOpportunity</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2956e54f-0eb5-42e2-a654-57028059caf7</UKGProToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
</s:Header>
  <s:Body>
  <DeleteOpportunity xmlns="http://www.ultimatesoftware.com/services/developmentopportunity">
  <entities xmlns:b="http://www.ultimatesoftware.com/contracts" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <b:DevelopmentOpportunity>
<b:Active>false</b:Active>
  <b:ApplicationId>10</b:ApplicationId>
<b:Category i:nil="true" /> 
<b:ContinuingEducationUnit>0</b:ContinuingEducationUnit> 
<b:Cost>0</b:Cost> 
<b:CourseCode i:nil="true" /> 
<b:CreatedBy i:nil="true" /> 
<b:DeliveryMethod i:nil="true" /> 
<b:Description i:nil="true" /> 
<b:IntegrationId>1001</b:IntegrationId> 
<b:License i:nil="true" /> 
<b:OpportunityId>0</b:OpportunityId> 
<b:Provider i:nil="true" /> 
<b:Title i:nil="true" /> 
<b:URL>http://sample.ultmatesoftware.com</b:URL> 
<b:UpdatedBy i:nil="true" /> 
</b:DevelopmentOpportunity>
</entities>
</DeleteOpportunity>
</s:Body>
</s:Envelope>

GetOpportunityByIntegrationId

<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/developmentopportunity/IDevelopmentOpportunity/GetOpportunityByIntegrationId</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2956e54f-0eb5-42e2-a654-57028059caf7</UKGProToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
</s:Header>
  <s:Body>
  <GetOpportunityByIntegrationId xmlns="http://www.ultimatesoftware.com/services/developmentopportunity">
<integrationId>1001</integrationId> 
</GetOpportunityByIntegrationId>
</s:Body>
</s:Envelope>

GetOpportunityIdByIntegrationId

<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/developmentopportunity/IDevelopmentOpportunity/GetOpportunityIdByIntegrationId</a:Action> 
<ultiproToken xmlns="http://www.ultimatesoftware.com/foundation/authentication/ultiproToken">2956e54f-0eb5-42e2-a654-57028059caf7</UKGProToken> 
<ClientAccessKey xmlns="http://www.ultimatesoftware.com/foundation/authentication/clientaccesskey">UGIYS</ClientAccessKey> 
</s:Header>
  <s:Body>
  <GetOpportunityIdByIntegrationId xmlns="http://www.ultimatesoftware.com/services/developmentopportunity">
<integrationId>1001</integrationId> 
</GetOpportunityIdByIntegrationId>
</s:Body>
</s:Envelope>