# Jobs ```{toctree} --- glob: hidden: --- 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: ```powershell # 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: ```powershell #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](). ```powershell #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 ```{image} /img/jobprocessor/jobs/job_types.png :width: 300px ``` 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). ```{image} /img/powerJobsSettingsDialog_QueuingJobs.png :width: 700px ``` 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. ```{image} /img/pj-gs-004-addjob.png :width: 580px ``` 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](): 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 ### 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: ```powershell 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](): ```json { "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_: ```powershell 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. ```{image} /img/jobprocessor/jobs/jobqueue_failedjob.png :width: 850px ``` 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]().