Integrate PowerShell with Rampiva Automate

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 


Instructions

A. Submit a Job and Monitor Its Progress

1

Login to Rampiva Automate using an API Key and perform a test query retrieving the user settings.

Update the $ServiceLocation variable to reflect the URL under which Scheduler is accessible.

Update the $authHeader variable with the value one obtained when configuring the Rampiva API Key. See https://rampiva.atlassian.net/wiki/spaces/KB/pages/1130921985 for instructions on how to create an API Key.

If Automate is accessible over HTTPS, ensure a valid certificate is deployed otherwise the PowerShell script will fail. Only use HTTP for testing if running the PowerShell script from the same server on which Scheduler is installed to avoid sending the authentication credentials in clear-text over the network.

If the authentication is successful, a message similar the the following will be returned:

Querying the user settings endpoint returned @{JOB_QUEUE_SORT=; datasetOption=; jobCardDesigner=; defaultValues=; BUILTIN=}

1 2 3 4 5 6 7 8 9 10 [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"
2

Define a function that will query Rampiva objects (such as Resource Pools) by name and return the object.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 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 }
3

Get the IDs of the Rampiva objects that will be used for the Job submission.

A successful execution will return an output similar to:

Endpoint scheduler/resources/resourcePools returned 5 objects(s)
Resource Pool Pool A has ID ae812386-2466-4848-b0ae-ac00375ff4fd
Endpoint scheduler/resources/executionProfiles returned 1 objects(s)
Execution Profile Default Profile has ID c0261c37-5dc6-4ba6-81e0-78b009f41bf5
Endpoint scheduler/client returned 3 objects(s)
Client Citrus Foods has ID 124ac055-0185-4d08-b1d2-ac402624d0b9
Endpoint scheduler/client/124ac055-0185-4d08-b1d2-ac402624d0b9/matters returned 3 objects(s)
Matter Project Grapefruit has ID cdab5497-574f-4e92-85a1-8f2c3bec47e8
Endpoint scheduler/library returned 3 objects(s)
Library Sample Library has ID 11e60e9e-5117-4fa3-bd3d-8edacef069f5
Endpoint scheduler/library/11e60e9e-5117-4fa3-bd3d-8edacef069f5/workflows returned 1 objects(s)
Workflow Sample eDiscovery Processing has ID a4101e0c-1e90-4371-9085-52df58e484fd

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 $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
4

Display the parameters that need to be filled out during the Job submission.

A successful execution will return an output similar to:

Workflow Sample eDiscovery Processing has 3 required parameters:
{nuix_case_location}
{source_data_location}
{docid_prefix}

1 2 3 4 5 6 $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 }
5

Prepare the Job submission.

A successful execution will return an output similar to:

Job Submission:
{
"libraryWorkflowId": "a4101e0c-1e90-4371-9085-52df58e484fd",
"name": "Sample Job from Powershell",
"sessionParameters": [
{
"value": "Case PS1",
"name": "{nuix_case_location}"
},
{
"value": "Source PS1",
"name": "{source_data_location}"
},
{
"value": "PS",
"name": "{docid_prefix}"
}
],
"priority": "MEDIUM",
"matterId": "cdab5497-574f-4e92-85a1-8f2c3bec47e8",
"resourcePoolId": "ae812386-2466-4848-b0ae-ac00375ff4fd",
"executionProfileId": "c0261c37-5dc6-4ba6-81e0-78b009f41bf5"
}

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 # 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
6

Submit the Job.

A successful execution will return an output similar to:

Job Sample Job from Powershell submitted with ID 04ad2fe3-586f-4753-8f16-4000833fd154

1 2 3 4 5 6 7 8 9 # 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
7

Monitor the Job progress until it ends.

A successful execution will return an output similar to:

06/21/2021 11:12:46 Sample Job from Powershell status: NOT_STARTED percentage complete: 0.0 %
06/21/2021 11:12:47 Sample Job from Powershell status: NOT_STARTED percentage complete: 0.0 %
06/21/2021 11:12:48 Sample Job from Powershell status: NOT_STARTED percentage complete: 0.0 %

06/21/2021 11:13:12 Sample Job from Powershell status: RUNNING percentage complete: 9.091818181818182 %
06/21/2021 11:13:13 Sample Job from Powershell status: RUNNING percentage complete: 18.182727272727274 %


06/21/2021 11:15:48 Sample Job from Powershell status: FINISHED percentage complete: 100.0 %

Engine log file: C:\Temp\Logs\rampiva-engine.60a4deb0-job.264d946e.log
Verifying prerequisites
All prerequisites are satisfied

Starting execution of workflow Sample Location Based on 6/21/21, 11:13 AM

If the Job does not ends with an FINISHED status, verify the values of the parameters submitted, and inspect the Job.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 # 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
8

Sample full script.

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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 # 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 # 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.