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.

Job Scripts

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 the job processor.

Job Entity type

A job can be associated to a Vault entity like Files or Items.

The declaration of the entity type for a job is a pre-requisite for using the powerJobs Settings Dialog.
Each job should be designed to support only a single entity type which must be specified in the according script file of the job. The entity type can not be edited in the settings dialog.

To assign a job to the entity type ‘File’, place the following Powershell comment in any line of the job script:

# JobEntityType = FILE

Possible entity types are:

Entity type	Description
FILE	Files
ITEM	Items
CO	Change Orders
CUSTENT	Custom Objects

Note

The definition, that one job should be desgined only for a single entity type and the subsequent assignment of the according entity type to the job has currently only impacts on the functionality of the powerJobs Settings Dialog.

Job Settings

Each job script can contain a one section that declares settings for the job.
The beginning of this section is marked by #region Settings and the end by #endregion.

All the PowerShell variables which are declared in this region can be easily configured in the powerJobs Settings Dialog.
If values are declared for those, then these are the default values of the displayed settings.
They can simply be edited without PowerShell experience if they are declared with simple data types:

Switch settings are displayed for Boolean values like $true or $false.
Text settings must be declared as single-line String variables. Their value must be enclosed in double quotation marks ("...") or single quotation marks ('...').
Text strings which contain such quote characters are stored with second consecutive quote characters.
Powershell settings are represented by text strings that begin with a dollar sign ($), such as $a, $my_var or $object.property.

A simple settings section could look like the following:

#region Settings
$pdfExportLocation = "C:\Exports\PDFs\"

$hidePDFinVault = $false

$myComputerName = $env:computername

$pdfNetworkFolder
#endregion

In order to provide more detailed information about a setting, a PowerShell comment can be specified in the line before the variable declaration.
The description is displayed alongside the setting in the powerJobs Settings Dialog.

#region Settings

# Path to the directory the PDF files should be exported to
$pdfExportLocation = "C:\Exports\PDFs\"

#endregion

More information on Creating custom Job Scripts.

Note

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.

Modules

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.

Registered Job Types

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.

Warning

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

Queueing Jobs

Depending on the requirements, there are different options to queue custom job types:

powerJobs Settings Dialog

For development purposes the “Submit Job” button of the powerJobs Settings Dialog can be used to queue a job manually. To do so, select the desired object (file, item, etc…) in Vault client and open the powerJobs Settings Dialog. After clicking the button, the job gets submitted with the highest priority (1).

The powerJobs Settings Dialog allows also to queue jobs automatically based on lifecycle state changes or manually by using context menu items.
These features require powerJobs Client to be installed on the workstations of interest.

Associate a job with a lifecycle transition in Vault

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 of a Vault File, Folder, Item or Custom Object the specified job will be queued.

Lifecycle Event Editor (for Change Orders)

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

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

PowerShell customizations

Alternatively it is recommended to trigger jobs 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.

The following example can be used on workstations where powerEvents is installed. As in the previous examples, jobs are automatically queued at certain lifecycle transitions.
Just create your own client customization using the folowing code:

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 1
	}
}

Jobs can be triggered for Vault Files, Folders, Items, CustomObjects and ChangeOrders this way, by passing the required parameters.

Time triggered

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"
  }
}

Errors

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.