UKG Pro Web Services API Guide

Reports-as-a-Service

Introduction

With UKG Pro Reports-as-a-Service, you can leverage your existing IBM Cognos reports to access your data without running the reports in the Cognos application. This document is intended for individuals who are familiar with software development, web service technologies, and IBM Cognos.

Reports-as-a-Service API

The UKG Pro Reports-as-a-Service API enables customers to feed integration needs by providing a programmatic interface to your UKG ProPeople Analytics Reports via a SOAP-based web service. By leveraging the integration between UKG Pro and Cognos, the API enables the integration of UKG Pro data in a variety of use cases from KPI dashboards and mashups to data replication and a custom reporting front-end.

With the UKG Pro Reports-as-a-Service API, reports become integration data sources. The API supports the execution of reports and subsequent retrieval of report output in standardized XML, comma-delimited, pipe-delimited, and space-delimited file formats. This flexibility enables maximum reuse of integration code. Any standard report can be utilized, and by using the Cognos report authoring tool, customers are able to create reports tailored specifically to the problem at hand.

In addition to report execution, the API supports the retrieval of report listings based on the permissions of the current user. Information about each report is provided, including the name and path of the report, and any input parameters the report may have.

The API offers several forms of security, using SOAP over HTTPS to ensure data is kept secure, and requiring all service clients to perform a login to authenticate. Authentication requires a valid Customer Identifier, an existing UKG Pro Service Account or UKG Pro user name and password, and a User API Key. Users are authorized using the same permissions configured in the UKG Pro portal, therefore no additional security steps are required.

Important: We recommend creating smaller reports as there is a 5-minute timeout when downloading reports.

Web Service Feature Highlights

Access all reports the user is authorized to see, including reports delivered by UKG and customer reports authored via Cognos Analytics.
Retrieve report properties including the report name, path (URL), and input parameters.
Run reports asynchronously and retrieve results as XML, with support for supplying input parameter values for dynamic report execution.
Streaming support avoids service call timeouts when retrieving large report results.
Authenticate using the same user credentials as the UKG Pro Web Portal.
Report XML provided by the service is the same XML report output generated when run from the web portal.

Technical Specifications

Simple Object Access Protocol (SOAP) 1.2
WS HTTP Binding
HTTPS / Secure Sockets Layer (SSL)
XML Data Format

Overview

Reports-as-a-Service gives developers access to build applications or perform automated tasks by leveraging Cognos to retrieve your UKG Pro data. 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
Data Format	XML
SSL Support	Required

Signup and Licensing

UKG Pro Account Required
Service Account or Web User with Web Services Permissions

Using a UKG Pro Service Account is recommended. For information regarding creating and maintaining a UKG Pro Service Account, refer to the document Manage Service Account guide available in the Learning Center.

Get Started

This section provides steps for creating a sample application in your development environment to retrieve data from an IBM Cognos report.

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.

Note: Service Accounts do not have access to Time Management or Recruitment report data. To access these reports, you must use a UKG Pro Web user account.

The Customer API key from the UKG Pro Web Service administrative page.

If you use a UKG Pro Service Account:

You need the User API key from the Service Account administrative page.
You must have appropriate permissions granted to the Service Account for the Reports-as-a-Service service. Before a service account can access BI via Reports-as-a-Service or Report Exports, you must submit a service case from the Customer Success Portal to request this.

If you use a UKG Pro Web User account, you need the User API key from the Web Service administrative page.

Report path of an IBM Cognos report that returns the data you desire. (Refer to section: Locating the Report Path in this document.)
Review the configuration section for recommended settings for your application.

Methods

This section introduces the API methods for Reports-as-a-Service.

Logon Method

The Logon method logs the user into the login service and starts your session.

The Logon method requires a log on request which is comprised of a user name, password, customer API key, and user API key. The customer and user API keys are automatically generated IDs. These IDs can be obtained by contacting your Named Support Representative.

GetReportList Method

Returns a list of the public IBM Cognos reports.

You can programmatically retrieve a list of reports and the path to the report. This is helpful if you are designing an application that allows the user to select the report they want to execute.

GetReportParameters Method

Retrieves a list of parameters for a report.

Use this method to return the list of parameters associated to a report. This is useful for creating applications that the user will enter the parameter values at execution time.

ExecuteReport Method

Runs a report request.

Use this method to execute the report and return a response object.

To run the report in a format other than XML, create a custom HTTP Header USDELIMITER with the value of the delimiter you would like. For example, for a:

Comma-delimited report, use US-DELIMITER: ,
Pipe-delimited report, use US-DELIMITER: |
Space-delimited report, use US-DELIMITER: SP

ReportStream Method

Returns the string that is the base 64 encoded version of a report.

This string must be decoded to return the actual output of the report. After the string is decoded, the service returns the output as a UTF-8 encoded string.

Use this to retrieve the ReportKey string.

Logoff Method

Runs a logoff request.

Use this method to end the session.

Locating the Report Path

Cognos 10

For Cognos 10, the report path is used to identify the report you want to execute. The report path can be found on the properties of the IBM Cognos report.

Launch IBM Cognos and navigate to the report list. Select the properties icon from the action column.

On the properties page, select the View the search path link which will display the view dialog. Copy the contents of the Search path input. This is the report path you need to pass to Reports-as-a-Service.

Configuration Settings

The following are guidelines for the binding settings in the app.config file on your local application. You may need to adjust these settings depending on the data you are retrieving.


<wsHttpBinding>
        <binding name="service" closeTimeout="00:02:00"
            openTimeout="00:02:00" receiveTimeout="00:10:00" sendTimeout="00:10:00"
            bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
            maxBufferPoolSize="524288" maxReceivedMessageSize="2147483647"
            messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
            allowCookies="false">
          <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
              maxBytesPerRead="4096" maxNameTableCharCount="16384" />
          <reliableSession ordered="true" inactivityTimeout="00:10:00"
              enabled="false" />
          <security mode="None">
            <transport clientCredentialType="Windows" proxyCredentialType="None"
                realm="" />
            <message clientCredentialType="Windows" negotiateServiceCredential="true" />
          </security>
        </binding>
      </wsHttpBinding>

Cognos 11

For Cognos 11, you can:

Request a list of all reports available via Reports-as-a-Service using the GetReportList Method. The properties will display the report search path. You can use that search path to run that report in Reports-as-a-Service.
Use the ID (as shown in the example screenshot below) from the UI > Properties page to run that report via Reports-as-a-Service.
Note: Do not copy and paste the sample code as there may be hidden characters that will generate errors.

In the C# example below, replace the ReportResponse code with:

    ReportResponse response =
        dataClient.ExecuteReport(
            new ReportRequest
            {
                ReportPath = “storeID(\"ID\")"
            },
            context);

In the XML examples below, replace the ReportPath code with the storeID value:

    <ReportPath>storeID("ID")</ReportPath>

C# Example

Generate the Service Reference

Once you have a user and a report, you need to create a service reference to the BI Data Service and the BI Streaming Service. In your development environment, add a service reference for each endpoint.

In Visual Studio, select the Add Service Reference menu item from the Project menu. Once you enter the service information you should have the reference display in the solution explorer.

Service Reference

Example Code

The following code is an example of running the IBM Cognos birthday report 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 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 BiDataServicesParametersSample.BiDataServices; using BiDataServicesParametersSample.BiStreamingService; using System; 
using System.Collections.Generic; 
using System.IO; using System.Linq; using System.ServiceModel; using System.ServiceModel.Channels; using System.Text; 
using System.Threading.Tasks; 
 
namespace BiDataServicesParametersSample 
{ 
    class Program 
    { 
        static void Main(string[] args) 
        { 
            BIDataServiceClient dataClient = new BIDataServiceClient("WSHttpBinding_IBIDataService"); 
            try 
            { 
 // Step 2: Logon the user to retrieve his/her data context
DataContext context = dataClient.LogOn(new LogOnRequest 
                        { 
                            ClientAccessKey = "ENXTX", 
                            UserName = "rcloud", 
                            Password = "password", 
                            UserAccessKey = "A1RCL0UD1979" 
                        }); 
 
// If the user successfully authenticates, execute the report
if (context.Status == ContextStatus.Ok) 
                { 
//note the following four lines set the US-DELIMITER header that causes the report output to be csv using the delimiter you set as the value of that header
                     
//valid values are: ",", "SP", "HT", any single character with a decimal ASCII code between 33 and 126 

//"SP" means space is the delimiter

//"HT" means horizontal tab(|) delimited 
                    using (new OperationContextScope(dataClient.InnerChannel)) 
                    { 
                        var httpHeader = new HttpRequestMessageProperty();  
//Comment out the next 2 lines of code if you do not want the output to be in CSV 
                        httpHeader.Headers["US-DELIMITER"] = ","; 
                        
OperationContext.Current.OutgoingMessageProperties[HttpRequestMessageProperty.Name] = httpHeader; 
 
// Step 3: Submit a report request
ReportResponse response =                         dataClient.ExecuteReport(new ReportRequest 
                            { 
                             ReportPath = "/content/folder[@name='UltiProBIContent']/folder[@name='UltiPro BI for Core HR and Payroll']/folder[@name='_UltiPro Delivered Reports']/folder[@name='Human Resources Reports']/report[@name='Employee Birthdays']", 
                                ReportParameters = new ReportParameter[] 
                                { 
                                    new ReportParameter 
                                    { 
                                        Name = "EmploymentStatus", 
                                        Value = "A", 
                                        Required = false, 
                                        DataType = "xsdString", 
                                        MultiValued = true 
                                    }, 
                                    new ReportParameter                                     { 
                                        Name = "Month", 
                                        Value = "11", 
                                        Required = false, 
                                        DataType = "xsdDouble", 
                                        MultiValued = true 
                                    } 
                                }                             },                             context); 

// Step 4: Get the report from the streaming service if the status is success 
                        if (response.Status == ReportRequestStatus.Success) 
                        { 
                            GetReportStreamFromResponse(response); 
                        } 
                        else 
                        { 
                            Console.WriteLine(response.StatusMessage); 
                        } 
                    }                 }                 else 
                { 
// Inspect the StatusMessage on an authentication failure 
                    Console.WriteLine(context.StatusMessage); 
                    Console.ReadKey(true); 
                } 
 
// Step 5: Logoff the user from the data service
dataClient.LogOff(context); 
            }             catch (Exception ex)    
// Some unexpected exception... 
            { 
       // Display any errors that may have occurred 
                Console.WriteLine(ex); 
            }           finally 
            { 
// Step 6: Finally, close or abort the client 
                CloseClientProxy(dataClient); 
            } 
 
            Console.Write("Press any key to exit..."); 
            Console.ReadKey(true); 
        } 
 
        /// <summary> 
        /// Opens a new connection to the streaming service and streams the results 
        /// into a file on the consumers file system 
        /// </summary> 
        /// <param name="response">The response object which contains the ReportRetrievalUri</param> 
        private static void GetReportStreamFromResponse(ReportResponse response) 
        { 
            string msg;             Stream input = null; 
            BIStreamServiceClient streamClient = null;             try 
            { 
                // Step 1: Create the stream client using the ReportRetrievalUri  
                //         provided by the ReportResponse object 
                streamClient = new BIStreamServiceClient("WSHttpBinding_IBIStreamService", new EndpointAddress(response.ReportRetrievalUri)); 
 
                // Step 2: Call the RetrieveReport method in a loop, exit the loop when  
                //         it is no longer in a Working state 
                ReportResponseStatus status;                 do                 { 
                    status = streamClient.RetrieveReport(response.ReportKey, out msg, out input); 
                } while (status == ReportResponseStatus.Working); 
 
    // Make sure that you succeeded in retrieving the report
if (status == ReportResponseStatus.Failed) 
                { 
                    Console.WriteLine("Failed to retrieve report due to \"{0}\"", msg);                     return; 
                } 
 
      // Step 3: Read the contents of the stream to its destination
using (StreamReader reader = new StreamReader(input)) 
                { 
                    using (Stream output = new FileStream("C:\\StreamOutput.xml", 
FileMode.Create, FileAccess.Write)) 
                    { 
                        using (StreamWriter writer = new StreamWriter(output)) 
                        { 
                            int bytesRead; 
                            char[] buffer = new char[1024]; 
                            while ((bytesRead = reader.Read(buffer, 0, buffer.Length)) > 0) 
                            { 
                                writer.Write(buffer, 0, bytesRead); 
                            } 
                        } 
                    } // will implicitly close the stream 
                }             }             finally 
            { 
     // Make sure that we close the stream, if we have one
if (input != null) 
                { 
                    input.Close(); 
                } 
 
                // Close or abort the client 
                CloseClientProxy(streamClient); 
            } 
        } 
 
        /// <summary> 
        /// Closes the channel which is currently being used by the client 
        /// </summary> 
        private static void CloseClientProxy(ICommunicationObject client) 
        { 
            if (client == null) return; 
 
            // In order to close the the channel we must first check if an error 
            // occurred on the channel (a.k.a. checking for a faulted state). 
            // If its not faulted call Close, otherwise call Abort
if (client.State != CommunicationState.Faulted) 
            { 
                // There is a small chance that the close method can cause  
                // an exception so we need to be extra safe and wrap it up 
            //in a try/catch
try                 { 
                    client.Close(); 
                }                 catch                 { 
                    client.Abort(); 
                } 
            } 
            else             {                 client.Abort(); 
            } 
        } 
    } 
}

// Example Quick Start Code End

XML Examples

For Cognos 11, in the XML examples below, replace the ReportPath code with the storeID value:

storeID("ID")

Login Request

<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/dataservices/bidata/2/IBIDataService/LogOn</a:Action>  
    <a:To s:mustUnderstand="1">https://servicehost/services/BiDataService</a:To>  
  </s:Header> 
  <s:Body> 
    <LogOn xmlns="http://www.ultipro.com/dataservices/bidata/2">   
      <logOnRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <UserName>username</UserName>  
        <Password>password</Password>  
        <ClientAccessKey>12345</ClientAccessKey>  
        <UserAccessKey>01234567890</UserAccessKey>  
      </logOnRequest> 
    </LogOn> 
  </s:Body> 
</s:Envelope>

Login Response

<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/dataservices/bidata/2/IBIDataService/LogOnResponse</a:Action>  
  </s:Header> 
  <s:Body> 
    <LogOnResponse xmlns="http://www.ultipro.com/dataservices/bidata/2">  
        <LogOnResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
          <ServiceId>551f6626-35cc-4239-b829-9d4e79d37de0</ServiceId> 
          <ClientAccessKey>RXD3C</ClientAccessKey> 
          <Token>807fd472-5196-49b2-bb4c-db7085f59796</Token>   
          <Status>Ok</Status> 
          <StatusMessage i:nil="true"/> 
          <InstanceKey>74e6c146-9bea-43b4-8432-df2755905f92</InstanceKey> 
        </LogOnResult> 
    </LogOnResponse> 
  </s:Body> 
</s:Envelope>

GetReportList

<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/dataservices/bidata/2/IBIDataService/GetReportList</a:Action>  
    <a:To s:mustUnderstand="1">https://servicehost/services/BiDataService</a:To>  
  </s:Header> 
  <s:Body> 
    <GetReportList xmlns="http://www.ultipro.com/dataservices/bidata/2"> 
      <context xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <ServiceId>3ccd26d5-94b2-4c0f-b88a-5ccfbe3d7fb0</ServiceId>  
        <ClientAccessKey>12345</ClientAccessKey>  
        <!-- GUID, unique per user session -->  
        <Token>b8f55e30-d68a-4815-a0de-27417ab7c242</Token>  
        <Status>Ok</Status>  
        <StatusMessage i:nil="true" />  
        <!-- GUID, unique per user session  -->  
        <InstanceKey>06366f8b-999f-433d-a429-aa50153f2d7c</InstanceKey>  
      </context> 
    </GetReportList> 
  </s:Body> 
</s:Envelope>

GetReportParameters

<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/dataservices/bidata/2/IBIDataService/GetReportParameters</a:Action>  
    <a:To s:mustUnderstand="1">https://servicehost/services/BiDataService</a:To>  
  </s:Header> 
  <s:Body> 
    <GetReportParameters xmlns="http://www.ultipro.com/dataservices/bidata/2"> 
      <reportPath>/content/folder[@name='UltiPro BI Content']/folder[@name='UltiPro BI for Core HR and Payroll']/folder[@name='_UltiPro Delivered 
Reports']/folder[@name='Human Resources Reports']/report[@name='Employee Birthdays']  </reportPath>  
      <context xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <ServiceId>3ccd26d5-94b2-4c0f-b88a-5ccfbe3d7fb0</ServiceId>  
        <ClientAccessKey>12345</ClientAccessKey>  
        <!-- GUID, unique per user session -->  
        <Token>b8f55e30-d68a-4815-a0de-27417ab7c242</Token>  
        <Status>Ok</Status>  
        <StatusMessage i:nil="true" />  
        <!-- GUID, unique per user session -->  
        <InstanceKey>06366f8b-999f-433d-a429-aa50153f2d7c</InstanceKey>  
      </context> 
    </GetReportParameters> 
  </s:Body> 
</s:Envelope>

ExecuteReport

<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/dataservices/bidata/2/IBIDataService/ExecuteReport</a:Action>  
    <a:To s:mustUnderstand="1">https://servicehost/services/BiDataService</a:To>  
  </s:Header> 
  <s:Body> 
    <ExecuteReport xmlns="http://www.ultipro.com/dataservices/bidata/2"> 
      <request xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <ReportPath>/content/folder[@name='UltiPro BI 
Content']/folder[@name='UltiPro BI for Core HR and 
Payroll']/folder[@name='_UltiPro Delivered Reports']/folder[@name='Human 
Resources Reports']/report[@name='Employee Birthdays']</ReportPath>  
          <ReportParameters> 
            <ReportParameter> 
              <Name>Month</Name>  
              <Value>1</Value>  
              <Required>false</Required>  
              <DataType>xsdDouble</DataType>  
              <MultiValued>true</MultiValued>  
            </ReportParameter> 
          </ReportParameters> 
        </request> 
        <context xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
          <ServiceId>3ccd26d5-94b2-4c0f-b88a-5ccfbe3d7fb0</ServiceId>  
          <ClientAccessKey>12345</ClientAccessKey>  
          <Token>b8f55e30-d68a-4815-a0de-27417ab7c242</Token>  
          <Status>Ok</Status>  
          <StatusMessage i:nil="true" />  
          <InstanceKey>06366f8b-999f-433d-a429-aa50153f2d7c</InstanceKey>  
        </context> 
      </ExecuteReport> 
  </s:Body> 
</s:Envelope>

RetrieveReport (buffered method)

Endpoint: http://serviceHost/services/BiDataStream 
  Headers: 
    Content-Type: application/soap+xml; charset=utf-8  
Request: 

<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/dataservices/bistream/2/IBIStreamService/RetrieveReport</a:Action>  
    <h:ReportKey xmlns:h="http://www.ultipro.com/dataservices/bistream/2" xmlns="http://www.ultipro.com/dataservices/bistream/2">a3f7fee3-8920-4047-a9f1-
33f673c343f5</h:ReportKey>  
    <a:To s:mustUnderstand="1">https://servicehost/services/BIStreamingService</a:To>   
  </s:Header> 
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <RetrieveReportRequest  xmlns="http://www.ultipro.com/dataservices/bistream/2" />   
  </s:Body> 
</s:Envelope>

ReportStream (streaming method)

Endpoint: http://serviceHost/services/BiDataStream 
  Headers: 
    Content-Type: application/soap+xml; charset=utf-8  
Request: 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> 
   <s:Header> 
     <h:ReportKey xmlns:h="http://www.ultipro.com/dataservices/bistream/2" xmlns="http://www.ultipro.com/dataservices/bistream/2">793ad910-aa2f-47f1-9d32-
0514423b8c3b</h:ReportKey>  
  </s:Header> 
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <RetrieveReportRequest xmlns="http://www.ultipro.com/dataservices/bistream/2" />  
  </s:Body> 
</s:Envelope>

Logoff

<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/dataservices/bidata/2/IBIDataService/LogOff</a:Action>  
    <a:To s:mustUnderstand="1">http://servicehost/services/BiDataService</a:To>  
  </s:Header> 
  <s:Body> 
    <LogOff xmlns="http://www.ultipro.com/dataservices/bidata/2"> 
      <context xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <ServiceId>04873c39-fe29-4cad-9842-9a5c4a289758</ServiceId>  
        <ClientAccessKey>12345</ClientAccessKey>  
        <Token>b58358a0-c9cf-43b2-b9ce-eb63d0c52b9c</Token>  
        <Status>Ok</Status>  
        <StatusMessage i:nil="true" />  
        <InstanceKey>f8f65ba1-87de-4ac4-950a-104c1754c5e2</InstanceKey>  
      </context> 
    </LogOff> 
  </s:Body> 
</s:Envelope>

Using Parameters

If your report requires a parameter, it is possible to add this to the XML. For instance, if you want to retrieve a report for a particular pay date, you can add the following parameter in your C# code:

ReportParameter param = new ReportParameter
{Name = "PayDate", Value = "2014-06-06T00:00:00"}