powerjobs_processor:jobprocessor:jobs

Jobs

powerJobs Processor extends the Vault Job Processor and allows the creation of custom job types in form of PowerShell scripts.
These Scripts and Modules are then executed in a prepared environment by the job processor when a job of that type is queued.
The PowerShell environment is partly prepared by the Setup_Job script which can also be customized.
These jobs can be used to perform various task.

All Job scripts need to be valid PowerShell scripts with the file extension .ps1 that are stored in the directory %ProgramData%\coolOrange\powerJobs\Jobs.

This directory contains a few sample jobs for most supported file conversions using the provided cmdlets.
New job scripts can be created or placed in the Jobs directory but they need to be registered before they can be executed by job processor.

More information on Creating Job Scripts.

If changes are made to a script while the Job Processor is running, the changes will be recognized the next time the job is executed.

Module files need to be valid PowerShell script modules with the file extension .psm1. It is recommended to give the Modules a descriptive name, for instance myCompany.NetworkStorage.psm1.
All Module files are located in %ProgramData%\coolOrange\powerJobs\Modules and are automatically imported for jobs executed by the Job Processor and when the powerJobs module is imported.

Following modules are delivered with the product:

  • coolOrange.Applications.psm1
  • coolOrange.FileSystem.psm1

coolOrange.FileSystem

Contains functions to work with the computers FileSystem.
One important function is the Clean-Up for cleaning up folders downloaded and generated files from your FileSystem after executing the job.

coolOrange.Applications

Contains functions to simplify the access to the Applications used by the powerJobs Processor.
These functions are just wrapping calls to the $Host.Applications object in order to use it in a more powerShell fashioned way e.g Get-Application.

Each Job Processor only handles jobs of specific types that are assigned to that instance. To see which types are enabled, open the “Job Types” dialog, which can be found in the “Administration” menu of the Job Processor.
The dialog displays all registered job types for this instance and whether they are processed or not.
To register a new job type the automatic synchronization of the Extended Job Processor UI can be used. Alternatively it is also possible to register the job type manually by extending the PowerJobs Processor.vcet.config file.

If there is an entry for a job type, but it is not checked, the Job Processor most likely cannot find the associated job script (.ps1 file) or it is not valid.

Adding or removing registered job types always requires restarting the Job Processor for the changes to apply.

There are different options to queue custom job types.

For development purposes the Vault Client Extensions Job Dialog can be used to queue a job manually.

To automate or assist workflows it is possible configure Vault to automatically queue jobs on Vault lifecycle changes.
Each single Vault lifecycle state transition must be extended with the according Job Type.

Afterwards when changing the state for a Vault File, Folder, Item or Custom Object, this will automatically queue the specified job.

For Change Orders jobs can be configured to be automatically queued when they reach the desired state, by using the Lifecycle Event Editor:

  1. Get and extract the application from GitHub
  2. Run the executable LifecycleEventEditor.exe
  3. Login to Vault (a user with administrative privileges is recommended)
  4. Navigate to the “Change Order” tab and select the default Workflow from the dropdown menu
  5. Select the desired transition (e.g. Approved → Close)
  6. Click on “Actions” → “Add Job to Transition” and add the job type without extension (e.g. “MyCompanyName.CreatePDF”)
  7. Click on “Actions” → “Commit Changes” to save your actions and proceed then to close the application


Alternatively it is recommended to trigger jobs within a custom powerEvents script by using the Add-VaultJob cmdlet as the Priority of the created Job can be configured this way.
Jobs with higher priority will be executed first. The lower the number the higher the priority.

Register-VaultEvent -EventName UpdateFileStates_Post -Action {
   param($files, $successful)
   
      foreach($file in $files)
      {
         $job = Add-VaultJob -Name "MyCompanyName.CreatePDF" -Parameters @{"EntityId"=$file.Id;"EntityClassId"="FILE"} -Priority High
      }
}
Jobs can be triggered for Vault Files, Folders, Items, CustomObjects and ChangeOrders this way, by passing the required parameters.


Time triggered jobs can be configured so that they are executed in a specific Interval by creating a “{Job Name}.settings” file in the Jobs directory:
{
 "Trigger":
  {
    "TimeBased": "0 0 8 ? * MON,TUE,WED,THU,FRI *",
    "Vault": "Vault",
    "Priority": 10,
    "Description": "This job is triggered weekdays at 8:00 am"
  }
}
It is also possible to configure the job Priority within this settings file.

In job scripts powershell's throw keyword should be used to raise exceptions manually and they can be handled with try/catch blocks:

try{
    $files = $vaultConnection.FileManager.AcquireFiles($settings)
}
catch{
    throw("Failed to acquire files")
}
By default the script execution will terminate, because the $ErrorActionPreference variable is set to 'Stop'.
In order to change the PowerShell error handling behavior for all jobs globally, the variable can be changed in the Setup_Job.ps1 script.

When an exception is thrown within a job script, the job is marked with the status Failure in the Job Queue.
The exception messages can be found directly in the Result of the failed jobs.



Exception details of the failed job are displayed in Trace Window.
Additionally more detailed information about all the Warnings and Errors that where logged during the job execution can be found in there or in the logfile.