Jobs randomly fail with "Cannot bind parameter 'FileId'"

Issue

Occasionally some jobs fail with the error message:

Cannot bind parameter 'FileId' to the target. Exception setting "FileId": "Cannot convert null to type "System.Int64"."

The code that is used to create the job has been double checked to use a valid entity id and entity class id.

Cause

This behaviour is caused when a job had been created for a file version that was deleted before the job ran.

Per default powerJobs Processor will try to get the latest version of a file. This is done in the file "Setup_job.ps1" in the following lines of code:

"File" {
    $fileWithCorrectVersion = (Get-VaultFile -FileId $job.EntityId)
    $global:file = Get-VaultFile -FileId $fileWithCorrectVersion.MasterId
}

If the file version, for which the job had been created, doesn't exist anymore then the first Get-VaultFile will fail.

The same issue will occur if the job is created with an invalid EntityId

Testing how the issue actually is caused

If you are using custom code to add your job to the job queue double check that you are putting in the correct Ids. An easy way to do this is by adding some logging to "Setup_Job.ps1"

Open "C:\ProgramData\coolOrange\powerJobs\Setup_Job.ps1"
In line 16 add

Write-Host "EntityId = '$($job.EntityId)'"

Run the affected job and control the powerJobs Processor log window. You should see a line like EntityId = '' or EntityId = '123'. If your id is null it means you passed a null vlaue to the job. This menas the script you wrote to add the job is buggy.

If you see an actual id use "Get-VaultFile -FileId 123" where 123 should be your actual id. If the cmdlet returns a file object the id is valid.

This means the issue was probably caused by a purged file version.

Solution

Buggy Script Creation:

If the error is caused by custom code contact the creator and ask him to fix it

Caused by purged File Version:

If you are creating your jobs through the "custom jobs" feature in the Vault lifecycle transitions the only way to handle this currently is with user training.

Make sure not to use the purge function while the job queue is full. Every pending job has the chance to fail after a purge.
If your users are allowed to use the revision roll back instruct them to check the job queue first. They mustn't use it if there are pending jobs for the file they want to roll back. They have to wait for the jobs to finish or remove them manually before using the rollback.

If you are using custom code to add the jobs with powerEvents it is possible to modify powerJobs Processor to use the master id instead of the entity id to search for the latest file.

Open "C:\ProgramData\coolOrange\powerJobs\Setup_Job.ps1"
Modify the "File" case to look like this

"File" {
    if(-not $job.MasterId) {
        $fileWithCorrectVersion = (Get-VaultFile -FileId $job.EntityId)
    }
    $global:file = Get-VaultFile -FileId $fileWithCorrectVersion.MasterId
}

Also modify the code you are using to add the jobs to pass in a MasterId parameter instead of EntityId. If you are using our Add-VaultJob cmdlet this would look something like this

$null = Add-VaultJob -Name 'Sample.CreatePDF' -Description "Create PDF for file '$($file._Name)' with Id='$($file.Id)' and MasterId='$($file.MasterId)'" -Parameters @{
    MasterId = $file.MasterId
    EntityClassId = 'FILE'
}