View Source

note

The material in this document is for informational purposes only. The products it describes are subject to change without prior notice, due to the manufacturer’s continuous development program. Rampiva makes no representations or warranties with respect to this document or with respect to the products described herein. Rampiva shall not be liable for any damages, losses, costs or expenses, direct, indirect or incidental, consequential or special, arising out of, or related to the use of this material or the products described herein.

Introduction

This article describes how to write a PowerShell script that will connect to Rampiva Automate using the API and perform various actions such as submit a new Job using the required settings and parameters, change the priority of a Job, and cancel all running Jobs.

When creating a PowerShell script that performs other tasks, it can be useful to first manually perform the tasks in the Rampiva Automate web interface and to monitor the endpoints called and the responses received in the browser network tab. Additionally, the Rampiva API documentation is available at http://localhost/openapi, where localhost is the server where Automate is installed.

Prerequisites

Rampiva Automate 5.5 or later
Rampiva API Key (see Authenticate to Rampiva Automate with an API Key)

Instructions

A. Submit a Job and Monitor Its Progress

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$ServiceLocation = "http://localhost/api/v1"
$authHeader = "Bearer 265fa20a-ba69-47a0-aab5-034fba50e062:fzMQKFhuOb63ydsOFmJJtExe6mttWFSr"

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add('Authorization', $authHeader)

$response = $null
$response = Invoke-RestMethod "$ServiceLocation/scheduler/userSettings" -headers $headers -Method Get -ContentType "application/json"
Write-Host "Querying the user settings endpoint returned $response"    
function Get-Rampiva-Object {
	param(
         [Parameter(Mandatory=$true)]
         [string] $Name,
         [Parameter(Mandatory=$true)]
         [string] $Endpoint
	)

    $response = $null
    $response = Invoke-RestMethod "$ServiceLocation/$Endpoint" -headers $headers -Method Get -ContentType "application/json"
    if ($response -eq $null)
    {
        Write-Error Querying endpoint $Endpoint  failed 
    }
    Write-Host "Endpoint $Endpoint returned $($response.Length) objects(s)"

    Foreach ($item in $response)
    {
        if ($item.name -eq $Name)
        {    
            return $item
        }
    }
    Write-Error Could not find $Name using $Endpoint
    Exit
}
$ResourcePoolName = "Pool A"
$ExecutionProfileName = "Default Profile"
$ClientName = "Citrus Foods"
$MatterName = "Project Grapefruit"
$LibraryName = "Sample Library"
$WorkflowName = "Sample eDiscovery Processing"

# Get resources IDs
$ResourcePool = Get-Rampiva-Object -Endpoint "scheduler/resources/resourcePools" -Name $ResourcePoolName
Write-Host Resource Pool $ResourcePool.name has ID $ResourcePool.id

$ExecutionProfile = Get-Rampiva-Object -Endpoint "scheduler/resources/executionProfiles" -Name $ExecutionProfileName
Write-Host Execution Profile $ExecutionProfile.name has ID $ExecutionProfile.id

$Client = Get-Rampiva-Object -Endpoint "scheduler/client" -Name $ClientName
Write-Host Client $Client.name has ID $Client.id

$Matter = Get-Rampiva-Object -Endpoint "scheduler/client/$($Client.id)/matters" -Name $MatterName
Write-Host Matter $Matter.name has ID $Matter.id

$Library = Get-Rampiva-Object -Endpoint "scheduler/library" -Name $LibraryName
Write-Host Library $Library.name has ID $Library.id

$Workflow = Get-Rampiva-Object -Endpoint "scheduler/library/$($Library.id)/workflows" -Name $WorkflowName
Write-Host Workflow $Workflow.name has ID $Workflow.id
$workflowParameters= $null
$workflowParameters = Invoke-RestMethod "$ServiceLocation/scheduler/library/workflow/$($Workflow.id)/requiredSessionParameters" -headers $headers -Method Get -ContentType "application/json"
Write-Host Workflow $Workflow.name has $workflowParameters.Length required parameters:
Foreach ($workflowParameter in $workflowParameters){
    Write-Host `t $workflowParameter.name
}
# Prepare job submission
$JobName = "Sample Job from Powershell"

$sessionParameters = @(
    @{
        name="{nuix_case_location}"
        value="Case PS1"
    }
    
    @{
        name="{source_data_location}"
        value="Various Files"
    }

        @{
        name="{docid_prefix}"
        value="PS"
    }
)

$jobSubmission = @{
    name = $JobName
    executionProfileId = $ExecutionProfile.id
    resourcePoolId = $ResourcePool.id
    libraryWorkflowId = $Workflow.id
    matterId = $Matter.id
    priority = "MEDIUM" 
    sessionParameters = $sessionParameters
}


$json = $jobSubmission | ConvertTo-Json
Write-Host `nJob Submission:`n$json
# Submit job
$json = $jobSubmission | ConvertTo-Json
Write-Host `nJob Submission:`n$json

# Submit job
$jobSubmitted= $null
$jobSubmitted= Invoke-RestMethod "$ServiceLocation/scheduler/jobs" -headers $headers -Method Post -Body $json -ContentType "application/json"

Write-Host Job $JobName submitted with ID $jobSubmitted.id
# Monitor job progress
$endedStates = ("FINISHED","ERROR","STOPPED","CANCELLED")
$executionState=$null
while(-not $endedStates.contains($executionState)){

    $jobDetails= $null
    $jobDetails= Invoke-RestMethod "$ServiceLocation/scheduler/jobs/$($jobSubmitted.id)/details" -headers $headers -Method Get -ContentType "application/json"
    
    $currentDate = Get-Date -Format "MM/dd/yyyy HH:mm:ss"
    $executionState = $jobDetails.settings.executionState

    Write-Host $currentDate $JobName status: $jobDetails.settings.executionState percentage complete: $jobDetails.settings.percentageComplete%
    Start-Sleep -Seconds 1
}

# Write job log
Write-Host $jobDetails.executionLog


B. Change the Priority of a Job

1

Log in to Rampiva Automate - see Section A.

2

Define a function that updates the priority of a Job.

function Set-Rampiva-Job-Priority {
	param(
         [Parameter(Mandatory=$true)]
         [string] $JobId,
         [Parameter(Mandatory=$true)]
         [string] $Priority
	)

    $submission =@{
        "priority"=$Priority
    }


    $json = $submission | ConvertTo-Json
    $result = $null
    $result = Invoke-RestMethod "$ServiceLocation/scheduler/jobs/$JobId/settings" -Method Put -Body $json  -ContentType "application/json" -headers $headers            
    return $result.settings.priority    
}

3

Search for Jobs with the name containing the specific text from Powershell. If the Job is still in the NOT_STARTED state, then update the job priority to HIGH using the previously defined function.

A successful execution will return an output similar to:

Got 2 job(s)
Job [Sample Job from Powershell] matches filter
Job [Sample Job from Powershell] is not running, changing priority
Job [Sample Job from Powershell ] new priority: HIGH
Job [Project Grapefruit - Sample eDiscovery Processing] does not match filter from Powershell, skipping

If the Job is already running, then its priority cannot be changed anymore.

# Get Jobs
$filter = "from Powershell"

$jobs= $null
$jobs= Invoke-RestMethod "$ServiceLocation/scheduler/jobs" -headers $headers -Method Get -ContentType "application/json"
Write-Host "Got $($jobs.Length) job(s)"
Foreach ($job in $jobs)
{
    if ($job.Name.contains($filter))
    {
        Write-Host "Job [$($job.Name)] matches filter"
        if ($job.executionState -eq "NOT_STARTED")
        {
            Write-Host "Job [$($job.Name)] is not running, changing priority"            
            $newJobPriority = Set-Rampiva-Job-Priority -JobId $job.id -Priority "HIGH"
            Write-Host "Job [$($job.Name)] new priority: $newJobPriority"

        } else {
            Write-Host "Job [$($job.Name)] is in state $($job.executionState), skipping"
        }
    } else {
        Write-Host "Job [$($job.Name)] does not match filter $filter, skipping"
    }
}

4

Sample full script.

C. Stop All Running Jobs

1

Log in to Rampiva Automate - see Section A.

2

Define a function that stops a Job.

function Stop-Rampiva-Job {
	param(
         [Parameter(Mandatory=$true)]
         [string] $JobId
	)

    $submission =@{
        "command"="STOP"
    }


    $json = $submission | ConvertTo-Json
    $result = $null
    $result = Invoke-RestMethod "$ServiceLocation/scheduler/jobs/$JobId/execution" -Method Put -Body $json  -ContentType "application/json" -headers $headers            
    return
}

3

Search for running Jobs and stop them

A successful execution will return an output similar to:

Got 2 job(s)
Job [Sample Job from Powershell] is running, stopping
Job [Project Grapefruit - Sample eDiscovery Processing] is in state FINISHED, skipping

# Get running Jobs
$jobs= $null
$jobs= Invoke-RestMethod "$ServiceLocation/scheduler/jobs" -headers $headers -Method Get -ContentType "application/json"
Write-Host "Got $($jobs.Length) job(s)"
Foreach ($job in $jobs)
{
    if ($job.executionState -eq "RUNNING")
    {
        Write-Host "Job [$($job.Name)] is running, stopping"     
        Stop-Rampiva-Job -JobId $job.Id       
    } else {
        Write-Host "Job [$($job.Name)] is in state $($job.executionState), skipping"
    }
}

4

Sample full script.