# Jobs

```{toctree}
---
glob:
hidden:
---
jobs/*
```

powerJobs Processor extends the [Vault Job Processor](http://help.autodesk.com/view/VAULT/2022/ENU/?guid=GUID-DAE28A42-45C3-4501-9BF2-78EE2F42808D) 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](/jobprocessor/jobs/setup_job) is partly prepared by the [Setup_Job script](<jobprocessor/jobs/setup_job:setup_job.ps1>) 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](/jobprocessor/jobs/sample_jobs) for most supported [File Conversions](/jobprocessor/file_conversion) using the provided [Cmdlets](/jobprocessor/code_reference/cmdlets/).\
New job scripts can be created or placed in the Jobs directory but they need to be [registered](<jobprocessor/jobs:registered job types>) before they can be executed by the job processor.

### 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](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_booleans) values like `$true` or `$false`.
- **Text** settings must be declared as single-line [String](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2#including-quote-characters-in-a-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](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?#including-quote-characters-in-a-string) characters.

However, values can even be set to any other valid powershell expression.

A simple settings section could look like the following:

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

$hidePDFinVault = $false

$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\"

# Wheter the PDF should be displayed in the Vault Explorer or not
$hidePDFinVault = $false

#endregion
```

[powerjobs settings dialog]: /job_configuration.html#powerjobs-settings-dialog

More information on [Creating custom Job Scripts](/jobprocessor/jobs/creating_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](/jobprocessor/code_reference/cmdlets/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](/jobprocessor/code_reference/objects/host) object in order to use it in a more powerShell fashioned way e.g [Get-Application](<jobprocessor/code_reference/objects/host:remarks>).

### Registered Job Types

```{image} /jobprocessor/jobs/img/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](<jobprocessor:job synchronization>) of the [Extended Job Processor UI](<jobprocessor:extended jobprocessor 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

There are different options to queue custom job types.\
For development purposes the [powerJobs Settings Dialog] can be used to queue a job manually.

```{image} /img/job_dialog.png
	:width: 600px
```

To automate or assist workflows it is possible configure Vault to automatically queue jobs on [Vault lifecycle changes](https://support.coolorange.com/support/solutions/articles/22000250089-how-to-add-a-job-on-lifecycle-transition).\
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 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](https://github.com/koechlm/Vault-LifecycleEventEditor-Sample):

1. [Get](https://github.com/koechlm/Vault-LifecycleEventEditor-Sample/releases) 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 {doc}`powerEvents script <powerevents:event_scripts>` by using the {doc}`Add-VaultJob <powervault:code_reference/commandlets/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.

```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 High
	}
}
```

Jobs can be triggered for Vault [Files](<jobprocessor/code_reference/objects/file:remarks>), [Folders](<jobprocessor/code_reference/objects/folder:remarks>), [Items](<jobprocessor/code_reference/objects/item:remarks>), [CustomObjects](<jobprocessor/code_reference/objects/customobject:remarks>) and [ChangeOrders](<jobprocessor/code_reference/objects/changeorder:remarks>) this way, by passing the required parameters.

[Time triggered](<jobprocessor:time triggered jobs>) jobs can be configured so that they are executed in a specific Interval by creating a _"{Job Name}.settings"_ file in the [Jobs directory](<installation:install locations>):

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

It is also possible to configure the job _Priority_ within this settings file.

## Errors

In job scripts powershell's [throw](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_throw?view=powershell-5.1) 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](<jobprocessor/jobs/setup_job:$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](<jobprocessor/jobs/setup_job: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} /jobprocessor/jobs/img/jobqueue_failedjob.png
	:width: 900px
```

Exception details of the failed job are displayed in [Trace Window](<jobprocessor: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](<logging:logfile>).