You want to understand how to run People Analytics Reports as A service (RAAS). If you just want the sample Postman code, you can request that here. Please note that the last step of the process requires a few lines of PowerShell outside of Postman. For your reference, here’s the UKG documentation.

If you’re new to UKG APIs, you might start with our RestAPI example. It’s simpler and relies on some of the same setup.

Let’s dive in step by step.

Gather the values you need:

We have created six environment variables in an environment called UKG RAAS. You’ll need to supply values for each of these items. Please note: if you modify the code, know that Postman variables are CaSE sENSitive. (I learned that the hard way).

HostName

USCustomerAPIKey

UserName

Password

UserAPIKey

ReportID

When you work use both RAAS and the Rest APIs, you’ll see that the key variable names aren’t consistent even though they represent the same things. Here’s a cross reference of the values across the APIs and the application. Roses smelling as sweet by any other name. Or so they say.

The user must have appropriate access to Business Intelligence.

The user can be either a regular user or a web services user. However, to use a web services user with RAAS requires some work with support.

All these values can be found under Web services in the application

First, you can see the User API Key and the Customer API key (Called US Customer API Key in our environment).

Note the User API Key will display for the currently logged in User. So, you must be logged in as that user to get the correct key.

You’ll then see all the endpoints you could ever want.

The first part is the same all the way down. That’s what you’ll want to enter in hostname.

So, if the Business intelligence web service endpoint is:

https://enterprise1701.redthree.com/services/BiStreamingService

The Hostname for our example will be

Enterprise1701.redthree.com.

And yes, I am that geeky.

The report ID can be found in People Analytics aka Cognos BI.

To find the ID, find any place where the name of the report appears in a directory or in the recently used list. Highlight the options to the right and choose properties.

Under Properties, choose Advanced and copy the ID.

You can run any report you’d like. However, I’d suggest something small first. I use a list of Earnings Codes. I’ve included a simple Earnings Code listing with the sample code.

You should now have all the information you need.

Running the APIs

If you want to really understand this, I suggest getting the sample code. I had to decide whether to include the code as code boxes in the posts or include it as screen shots. Screen shots enabled me to point out key pieces so I’ve chosen screen shots.

Once you import the collection and the environment, you should see the four following requests.

If you set your environment variables, you should then be able to run the first three requests.

While it is possible to save output automatically within Postman, it’s not straightforward. So, you’ll be saving the output manually and then running a few lines of PowerShell to get your final CSV output.

I’m going to give an overview of each step. Each step uses variables from the environment or from previous steps. Each step returns values and data.

Headers

The only header value is content type:

Body

Uses the HostName, UserName, Password, USCustomerAPIKey, and UserAPIKey environment variables to get authorization.

Tests

If the Request is successful, the tests set three global variables:
raasServiceID
raasToken
raasInstance

Headers

There are two headers. The content type is the same as in the Login Request.

We also have “US Delimiter” which controls the final delivered output in the csv file in the next step.

Pre-Request Script

The specification requires that the ID be included in the XML with quotes.

So, if you have report ID 12345, it needs to be included in the XML as storeID(“12345”) in the XML. Using a variable eliminated issues escaping quotes. And I hate escaping quotes.

It was easiest to do this in a pre-request script.

Body

Uses the raasServiceID, raasToken, and raasInstance as well the REportIDXML variable to run the report.
Please note: This request only tells you whether it’s succeeded or failed. No data is returned.

Results

While no data is returned, you will see a success message in the results:

Tests

We have one test to set the global variable raasReportKey. This variable is used in the Retrieve Report Request.

Headers

Again, just the Content-Type

Body

Uses HostName and RaasReportkey to actually bring the report data down:

Results

Almost there.

If you look at the XML result body, you’ll see that the report completed.

And it’s put data into “Report stream”

Of course, if you’re not a computer, that data isn’t all that useful.

There are ways to save this to a file with code in Postman. However, the goal of this post is not to make you a Postman expert. So, we’re going to save the output and use a little PowerShell to make the data readable:

The first step is to save the data as a file

Click on the three dots above the output. Do not click on Save as Example.

Choose “Save Response to File”

You can save it under any name. I’d suggest using an XML extension.

Here’s the Powershell you need. It assume that the code runs in the same directory where you’ve save the file.

It simply pulls out the ReportStream. And then decodes it, saving it to a csv file.

It then display the file.

If you’re a PowerShell guru, you know that you could combine this into fewer lines. But I wanted to make is easier to understand.

[xml]$response = Get-Content -Path ".\Earnings Code Output.xml"
[string]$rptExpFile = ".\Earnings Code Output.csv"
[string]$ReportStream = $response.Envelope.Body.StreamReportResponse.ReportStream
[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($ReportString)) |
out-file $rptExpFile                      
Get-Content $rptExpFile | Out-GridViewCode language: PHP (php)

Once you have the csv file you can load this to SQL Server or any other application.

(I have a series of older posts on loading data to SQL from Excel which might be relevant. You’ll need to substitute import-csv for import-excel in the code. )

If you’ve got questions, ask away in the comments or contact us for a free 30-minute intro call.

Finally, we’ve built a standard set of powershell and SQL code that allows any report to be moved to SQL server. Once the report is written, it takes about an hour to do the necessary setup to get the report flowing to the database. Again, contact us if you’re interested.