powerjobs_processor:jobprocessor:applications

Applications

In a powerJobs Processor context, entities that support a specific set of operations e.g. opening or exporting a file, are referred to as Applications.
These Applications are used by the powerJobs Processor Cmdlets to perform their actions on documents. Available Applications can be accessed in the $host.applications variable in a Job Environment.
The product also provides an option to extend or implement new and existing Applications.

The following Applications are already implemented in the product:

ApplicationNote
InventorAutodesk Inventor supports opening, manipulating and converting 3D mechanical designs, and requires it's own license, also when running in a JobProcessor environment.
InventorServerInventor Server is a headless version of Autodesk Inventor.
It requires no additional license to purchase and you don't need a full version of Inventor installed.
It is noticeably faster in starting and processing jobs but there are no GUI features available.
DWG TrueViewDWG TrueView is a CAD file viewer that does not require any additional license to purchase and you don't need a full version of AutoCAD installed.
In contrast to AutoCAD, it only supports conversions to PDF and DWF formats. AutoCAD is currently not supported.

More details on the supported conversions for each Application can be found on the File Conversion page.

Custom applications can be used to extend the products export capabilities.
The product exposes a .NET interface that can be implemented and registered to make it available to the document relates cmdlets.

IApplication Interface

The API for Applications is designed around the IApplication interface and also includes types like IDocument, IExport, ect. and is designed as follows:

Visual Studio Project setup for Custom Applications

1. Create a new Solution in VisualStudio

The new project should have the following settings:

  • Output Type: Class Library
  • Target .Net framework: 4.7
  • Platform Target: Any CPU

2. Reference the assemblies coolOrange.GenerateEngine and powerJobs.Common

These assemblies contain the relevant interfaces and API to create your first Application.
After referencing the assemblies '%ProgramFiles%\coolOrange\Modules\powerJobs\coolOrange.GenerateEngine.dll' and '%POWERJOBS_PROCESSORDIR\%powerJobs.Common.dll' the flag CopyToOutput should be set to FALSE

3. Creating an IApplication implementation

Now we can create our own IApplication implementation.
The implementation has to handle the start/stop functionality.
In order to use the restarting-features of powerJobs Processor for having not having troubles with long running applications, we recommend to derive your class from the coolOrange.GenerateEngine.ApplicationBase, and implement the functionality IsRunning properly!
Note that the Application will only open documents configured in the IsSupportedFile (or SupportedFileTypes) functionality!

4. Creating an IDocument implementation

Implement the closing functionality of your document properly, in order to have no unmanaged resources lying around in memory later.
Note that the constuctor of your document can use the OpenDocumentSettings for opening the correct file.
Additional options coming from the Open-Document cmldet can be consumed too.
We recommend to derive your Document class from the coolOrange.GenerateEngine.DocumentBase class.
Our Application from Step 3 has to return an instance of this document when OpenDocument is called.
If the application is derived from coolOrange.GenerateEngine.ApplicationBase, you just need to return a new instance of your class in OpenDocument_Internal(OpenDocumentSettings openSettings).

After this step the cmdlets Open-Document and Close-Document should already work.
In order to use Export-Document the next steps are required too.

5. Creating an IDocumentExporter implementation

The exporter takes care about different export formats and decides which export should be used from Export-Document.
The Application property IDocumentExporter Exporter has to be set to an instance of this IDocumentExporter. We recommend to derive your DocumentExporter class from coolOrange.GenerateEngine.DocumentExporterBase class which handles multiple DocumentExports depending on the file format.
All your Exports can just be registered in this class later.

6. Creating an IDocumentExport implementation

In your Export you need to return a name (e.g. “PDF”), so the DocumentExporter can decide to take this export when required.
We recommend to derive your DocumentExport class from the coolOrange.GenerateEngine.DocumentExportBase class.
After deriving from the class implement all the abstract functions.
By specifying the SupportedDocumentTypes your export will be called only for the specified formats.
The real export logic has to be implemented in the Execute function.
You can use the ExportSettings to gain access to the options passed to the Export-Document cmdlet.

7. Build and deploy

Next copy your application assembly in a new folder under the Modules directory.

8. Register your application

Create a new module in the modules directory and register your application in there, similar to the default application:

Add-Type -Path "$($Env:POWERJOBS_MODULESDIR)\<YouApplicationFolder>\<YouApplicationAssembly>.dll"
Register-Application ([<NameSpace.YouApplicationClass>])
Now you can create your own job and pass to the Open-Document the application name of your new application:
Open-Document -Application <YourApplicationName> -LocalFile $file.LocalPath

9. Best practice: call the powershell console

Best practice is to call the powershell console for debugging purpose, and import the powerJobs module.

In VisualStudio you can configure the Debugging-Tab like this :
Start external program: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Command line arguments: -noexit -command “Import-Module powerJobs”

10. Press F5 and the powershell console

powerShell Console will start up and your application get's loaded: You can execute the commandlets and debug your application and exports!

powerJobs Processor should be installed on the development machine because the references are taken from the installation directory

Visual Studio Template

The Visual Studio Template creates a basic project similar to following the steps above.

Template Download

Visual Studio 2012
Download:
C# Template

Installation:
Copy the zip file to your VisualStudio Templates directory %userprofile%\documents\Visual Studio 2012\Templates\ProjectTemplates\coolOrange

Start VisualStudio and create a new project by using the project template powerJobs Processor Application and give your application a meaningful name (without characters like spaces or dots).



The assembly containing your application will be build to the Modules directory, with the same name as your project.
It is already configured to launch a powerShell Console and imports powerJobs automatically by pressing F5.

In order to use a custom application implementation it needs to be registered for the product to find it.
Registering an Application requires the .NET assembly containing the implementation to be loaded and calling the Register-Application cmdlet and passing the class implementing the IApplication interface.
There steps can be performed in powerShell with the following:

Add-Type -Path "$($Env:POWERJOBS_MODULESDIR)\<YouApplicationFolder>\<YouApplicationAssembly>.dll"
Register-Application ([<Namespace.YouApplicationClass>])