Powershell Examples

Running Jobs

Below is the Powershell Script that enables the user to run a Job programmatically.

Depending on the region of Data Governor you are using (AU or US), you are required to modify the script below accordingly. The $selectedHost line is referring to AU by default. To change it to US replace $AU with $US ($selectedHost = $US;).

# For US
$US = @{
    "idsHostname" = "identity-us.perspectiveilm.com";
    "apiHostname" = "dg-api-us.perspectiveilm.com";
};

# For AU
$AU = @{
    "idsHostname" = "identity-au.perspectiveilm.com";
    "apiHostname" = "dg-api-au.perspectiveilm.com";
};

# Change this to your selected host respectively.
$selectedHost = $AU;

# Comment out the appropriate 
$clientId = Read-Host -Prompt "Please provide a valid Client ID";

$accessHeaders = @{
    "grant_type"    = "client_credentials";
    "client_id"     = $clientId;
    "client_secret" = $clientId;
    "scope"         = "webApi"
};

$baseUrl = "https://$($selectedHost['apiHostname'])/api/v1/";

$accessToken = ((Invoke-WebRequest -Uri "https://$($selectedHost['idsHostname'])/connect/token" -Method Post -Body $accessHeaders).Content | ConvertFrom-Json).access_token;
$accessHeaders = @{"Authorization" = "bearer $accessToken" }

# Retrieve projects
$projectReq = (Invoke-WebRequest -Uri "$($baseUrl)Projects?pagenumber=1&pageSize=1000" -Headers $accessHeaders);
$projects = ($projectReq.Content | ConvertFrom-Json).items;

Write-Host -ForegroundColor Green -Object "Projects";
foreach ($proj in $projects.GetEnumerator()) {
    Write-Host "$($proj.projectId) - $($proj.projectName)";
}

# Save the project number, retrieve jobs for the project
$projectNumber = Read-Host -Prompt "Please provide the project ID you wish to search for jobs in";
$jobReq = (Invoke-WebRequest -Uri "$($baseUrl)Projects/$projectNumber/Jobs?pagenumber=1&pageSize=1000" -Headers $accessHeaders);
$jobs = ($jobReq.Content | ConvertFrom-Json).items;

Write-Host -ForegroundColor Green -Object "Jobs";

foreach ($job in $jobs.GetEnumerator()) {
    Write-Host "$($job.jobId) - $($job.jobName)";
}

# Save the job number, invoke the RunOnce endpoint.
$jobNumber = Read-Host -Prompt "Please provide the job ID you wish to execute";

$runOnceReq = (Invoke-WebRequest -Uri "$($baseUrl)Jobs/$jobNumber/JobExecutions/RunOnce" -Headers $accessHeaders);
# If 200, you ran the job.
if ($runOnceReq.StatusCode -eq 200) {
    Write-Host -ForegroundColor Green "Job with ID $jobNumber successfully queued for execution!";
}


$status = "";

do {
    Start-Sleep -Seconds 3;
    $status = ((Invoke-WebRequest -Uri "$($baseUrl)Jobs/$jobNumber" -Headers $accessHeaders).Content | ConvertFrom-Json).lastExecution.status;
    Write-Output "Current Status: $status";
}while ($status -ne "Success" -and $status -ne "Failure");

Write-Host -NoNewLine 'Press any key to continue...';
$null = $Host.UI.RawUI.ReadKey('NoEcho,IncludeKeyDown'); 

Viewing Job Execution Logs

The following snippet can be used for viewing the logs of a job for a specific execution.

Notable Details

  • The job execution and job execution log endpoints both use pagination. The pagingInfo object returned with the response can be used for determining the remaining pages to call as well as how large the payload being returned is.
    • This logic is standard for all paginated endpoints in the DGO API and so the same snippet of code can be used for multiple endpoints.
    • Most endpoints which return a list of entities are paginated.
# For US
$US = @{
    "idsHostname" = "identity-us.perspectiveilm.com";
    "apiHostname" = "dg-api-us.perspectiveilm.com";
};

# For AU
$AU = @{
    "idsHostname" = "identity-au.perspectiveilm.com";
    "apiHostname" = "dg-api-au.perspectiveilm.com";
};

# Change this to your selected host respectively.
$selectedHost = $AU;

# Comment out the appropriate 
$clientId = Read-Host -Prompt "Please provide a valid Client ID";

$accessHeaders = @{
    "grant_type"    = "client_credentials";
    "client_id"     = $clientId;
    "client_secret" = $clientId;
    "scope"         = "webApi"
};

$baseUrl = "https://$($selectedHost['apiHostname'])/api/v1/";

$accessToken = ((Invoke-WebRequest -Uri "https://$($selectedHost['idsHostname'])/connect/token" -Method Post -Body $accessHeaders).Content | ConvertFrom-Json).access_token;
$accessHeaders = @{"Authorization" = "bearer $accessToken" } 

# The Data Governor Online Logging levels and their human readable.
$LogLevels = @{
    "0" = "Trace";
    "1" = "Debug";
    "2" = "Information";
    "4" = "Error";
    "5" = "Critical";
    "6" = "None";
}

# Retrieves a page of job executions based on the provided Job Id.
function Get-JobExecutions(
    [int]$JobId, 
    [int]$PageNumber = 1,
    [int]$PageSize = 100,
    [boolean]$Reverse = $true) {
    $QueryParams = @{
        "pageNumber"         = $PageNumber;
        "pageSize"           = $PageSize;
        "itemsToSkipInQuery" = 0;
        "maxItemsInQuery"    = $PageSize;
        "reverse"            = $Reverse.ToString();
    }
    $RequestUrl = "$($baseUrl)Jobs/$JobId/JobExecutions";
    $Response = Invoke-WebRequest -Uri $RequestUrl -Headers $accessHeaders -Method Get -Body $QueryParams;
    return (ConvertFrom-Json -InputObject $Response.Content);   
}

# Retrieves a page of logs for a Job Execution based on the provided id.
function Get-JobExecutionLogs(
    [int]$JobExecutionId,
    [int]$PageNumber = 1,
    [int]$PageSize = 100,
    [boolean]$Reverse = $false) {
    $QueryParams = @{
        "pageNumber"         = $PageNumber;
        "pageSize"           = $PageSize;
        "itemsToSkipInQuery" = 0;
        "maxItemsInQuery"    = $PageSize;
        "reverse"            = $Reverse.ToString();
    }
    $RequestUrl = "$($baseUrl)Logs/App/JobExecutions/$JobExecutionId";
    $Response = Invoke-WebRequest -Uri $RequestUrl -Headers $accessHeaders -Method Get -Body $QueryParams;
    return (ConvertFrom-Json -InputObject $Response.Content);   
}

$JobId = Read-Host "Please provide a Job ID to retrieve executions for"
$JobExecutions = Get-JobExecutions -JobId $JobId;
foreach ($JobExecution in $JobExecutions.items) {
    Write-Output "$($JobExecution.jobExecutionId) - $($JobExecution.status)"
}

$JobExecutionId = Read-Host "Please select one of the Job Execution IDs from above to view the logs for";
$Logs = Get-JobExecutionLogs -JobExecutionId $JobExecutionId;

$CurrentPage = 1;
$MaxPage;
# Iterate through log pages
do {
    $CurrentPage = $Logs.pagingInfo.pageNumber;
    $MaxPage = $Logs.pagingInfo.totalPages;

    # Format Log Messages in a readable manner
    foreach ($Log in $Logs.items) {
        $LogTime = $Log.logDateTime;
        $LogLevel = $LogLevels[$Log.logLevel.ToString()];
        $LogMessage = $Log.logMessage;
        Write-Output "$LogTime - [$LogLevel] $LogMessage";
    }

} until ($CurrentPage -eq $MaxPage)