Command Line Interface Setup

Overview

The validatarcli command-line application allows jobs to be executed from an external scheduler. The domain account running the validatarcli application will be used to authenticate the user into Validatar, so the command line does not require any credentials. The following steps can be used to install validatarcli on an application server – this assumes that Validatar has already been installed on a separate web server.

Access Requirement for Job Execution

The user launching the job must have access to the application server to execute the job via the command line.

Configuration

1. Make sure .NET Runtime 8.0.x has been installed on the application server. You can download it here, if necessary.

   1. NOTE: On that page, scroll past the ASP.NET Core Runtime 8.0.x and .NET Desktop Runtime 8.0.x sections to the .NET Runtime 8.0.x section and download the Windows x64 installer.

2. Download and run the validatarcli-setup.msi installer from here: https://admin.validatar.com/releases.

3. Ensure that the domain account that will be used for authentication has been added to a Validatar user profile.

Testing The Command Line

1. In Validatar, under Settings > Users, add the Windows AD or domain account to the user's profile who will execute the job if it hasn't been added already.

2. Navigate to the job you want to execute.

3. Grab the job ID which is the last number in the URL.

4. Using the application server that you want to externally run the job on, open up a command prompt.

5. Navigate to the folder that you installed validatarcli to in step 2 of the configuration section above. You may have to change directories using the cd command. We're using the Z:\ drive in the example below.

6. After navigating down to the folder, type validatarcli

7. Press Enter.

8. The Validatar commands should appear on the next two lines.

9. Next type validatarcli -j [insert job ID]. Be sure to include a space between -j and the job ID.

10. Press Enter. The job will now execute.

11. The exit code that appears refers to the result of the job.

12. Navigate back to Validatar, under Results, to be sure the job executed correctly and displayed the proper exit code in the command prompt.

    

Integrating Validatar with an External Tool

After you confirm that you're able to execute jobs via command line, you can include this in your external scheduler workflow. You can either kick off a Validatar job externally or based on the result of the Validatar job, kick off an external job.

A way to do this is to create a Powershell host script to call the Validatar CLI. If you want to kick off an external job based on the result of the Validatar job, you can configure your script to release the appropriate external job based on the return code of the CLI. You may need to refer to the external tool's documentation to get the syntax for a job-release.

When building out the process, it's highly recommended to use parameters or extended properties as much as possible. That will make the process more flexible and easier to change.

Example Powershell Scripts

We've provided a couple of Powershell scripts that you can use to initiate jobs from the Validatar CLI or Rest API.

Validatar CLI Job Execution

# Set variables needed for the Validatar API calls
$Validatar_TVAdmin_JobCode = "YOUR_JOB_ID"
$Validatar_TVAdmin_CLI_EXE = "YOUR_CLI_EXE_FILE_LOCATION"
$Validatar_TVAdmin_StdOut_Location = "YOUR_StdOut_Location"
 
# These are the various return codes that can be returned by/retrieved from Validatar's TVAdmin command line tool
enum enum_Validatar_ReturnCode {
    Success      = 0   # the Validatar job executed and all tests passed
    Unauthorized = 1   # User is unauthorized to run this Validatar Job
    Job_Failure  = 2   # The Validatar Job failed
    Test_Failure = 3   # The Validatar job executed with at least one test failure
    Error        = 4   # The Validatar job executed with at least one error
}
# I'm doing this to properly set the initial object type of $Validatar_ReturnCode as an enum
$Validatar_ReturnCode = [enum_Validatar_ReturnCode]::Success
 
# Now start the process of setting things up to get a Validatar Job started
$Final_Validatar_TVAdmin_StdOut_Location = $Validatar_TVAdmin_StdOut_Location.Trim('"')
$ProcessObject = Start-Process -FilePath $Validatar_TVAdmin_CLI_EXE.Trim('"') -ArgumentList "-j $Validatar_TVAdmin_JobCode" -PassThru -Wait -RedirectStandardOutput $($Final_Validatar_TVAdmin_StdOut_Location.replace("`$sequence", $sequence))
# See enum_Validatar_ReturnCode above for valid Validatar return codes  
[int]$Validatar_TVAdmin_ExitCode = $ProcessObject.ExitCode
# Now need to convert from an actual integer return code from Validatar into the appropriate Enum status for Validatar
$Validatar_ReturnCode.value__ = $Validatar_TVAdmin_ExitCode
Write-Output "Validatar_TVAdmin_ExitCode = $Validatar_TVAdmin_ExitCode"
Write-Output "Validatar_ReturnCode = $Validatar_ReturnCode"

Validatar REST API Job Execution

# Define an enum for the Validatar return codes
enum enum_Validatar_ReturnCode {
    Success      = 0   # the Validatar job executed and all tests passed
    Unauthorized = 1   # User is unauthorized to run this Validatar Job
    Job_Failure  = 2   # The Validatar Job failed
    Test_Failure = 3   # The Validatar job executed with at least one test failure
    Error        = 4   # The Validatar job executed with at least one error
}
# Set variables needed for the Validatar API calls
$projectId = "YOUR_PROJECT_ID"
$jobId = "YOUR_JOB_ID"
$token = "YOUR_X-TV-API-TOKEN"
$baseUrl = "YOUR_BASE_URL"
# Construct the URL for the job execution API call
$postApiUrl = "$baseUrl/core/api/v1/Execution/projects/$projectId/jobs/$jobId/execute"
# Output the URL to the console for debugging purposes
$postApiUrl
# Construct the JSON object for the job execution request
$body = @{
    "waitUntilComplete" = $true
    "sourceId" = 150
} | ConvertTo-Json
# Set the headers for the API calls
$headers = @{
    "Content-Type" = "application/json-patch+json"
    "x-tv-api-token" = "$token"
}
# Send the job execution request to the Validatar API
$response = Invoke-RestMethod -Uri $postApiUrl -Method Post -Headers $headers -Body $body
# Construct the URL for the job results API call using the batch ID from the job execution response
$getApiUrl = "$baseUrl/core/api/v1/Execution/projects/$projectId/jobs/$jobId/results/"
$batchId = $response.batchId
$resultsUrl = $getApiUrl + $batchId
# Send the job results request to the Validatar API
$results = Invoke-RestMethod -Uri $resultsUrl -Method Get -Headers $headers
# Count the number of tests that passed, failed, and resulted in an error
$passedCount = 0
$failedCount = 0
$errorCount = 0
foreach ($test in $results.tests) {
    switch ($test.status) {
        "Passed" { $passedCount++ }
        "Failed" { $failedCount++ }
        "Error" { $errorCount++ }
    }
}
# Output the test counts to the console for debugging purposes
"Passed: $passedCount, Failed: $failedCount, Error: $errorCount"
# Determine the Validatar return code based on the test counts
if ($errorCount -gt 0) {
    return [enum_Validatar_ReturnCode]::Error
}
elseif ($failedCount -gt 0) {
    return [enum_Validatar_ReturnCode]::Test_Failure
}
elseif ($passedCount -gt 0) {
    return [enum_Validatar_ReturnCode]::Success
}
else {
    return [enum_Validatar_ReturnCode]::Job_Failure
}
# Return the final enum Code
$enum_Validatar_ReturnCode