# Hot Folders

Hot Folders automation allows you to drive Phoenix without human interaction using input and output folders. A total of 35 actions are available, supporting several workflows in Phoenix including die template, artwork imposition and the powerful Imposition AI tools: Impose, Populate, Optimize, and Plan. In addition, all export and report formats found in Phoenix are supported.

Hot folders are driven by XML files. In addition, scripting is available using a pre-defined JavaScript interface to support non-XML inputs (PDF, CSV, etc), custom logic, notifications for success and error cases, and much more.

Real-time activity for each hot folder can be monitored with Hot Folder View. This view displays a list of log messages detailing all actions that have taken place as well as an overview of all successful and failed jobs. Search filtering is available to find jobs with specific IDs, log entries related to specific actions, and more.

# Configuring Hot Folders

Hot folders are created, edited and removed in the Automate Panel. To access the Automate Panel, go to the Windows menu and select "Automate". The Automate Panel shows all hot folders you have created and shows status, processed task and error counts.

To create a new hot folder, click on the dropdown icon in the upper-left corner of the Automate Panel and select "New Hot Folder..." from the menu. For detailed info on the parameters for setting up a hot folder, see the Automate section of the User Guide.

To edit hot folder settings, the hot folder must first be stopped. Next, right click on the hot folder in the Automate Panel and select "Edit...". This will launch the Hot Folder Dialog where changes can be made to any parameter of the hot folder.

If you made changes to the Actions XML or Script file and want to reload them, you can do so by editing the hot folder and re-loading. Alternatively, you can just right click on the hot folder in the Automate Panel and select "Reload Actions/Script" which will reload the files in one step.

# Hot Folder View

Overview: For each hot folder you can get a real-time activity view by entering Hot Folder View. To enter Hot Folder View, double click on the hot folder in the Automate Panel or right click on the hot folder and select "Hot Folder View".

Hot Folder View is opened in the Artboard as a separate tab. This means you can open multiple Hot Folder Views simultaneously and switch between them and active jobs by using the Artboard tabs.

Main Log: Within Hot Folder View, the main list of log entries takes up the right side of the view. Logs are updated in real time. Log entries containing paths are hyperlinked to quickly open the file. This is especially useful for export or report actions and the Save Job action where clicking on the saved job path will open the job directly in Phoenix.

Search: Above the log table is a Search text box. Entering text into the Search box and pressing enter will filter the list of log entries to those entries containing the search text. To clear search and view all log entries again, click the 'X' icon on the far-right side of the Search text box.

Tasks List: In the upper left panel of Hot Folder View is the Tasks List. This is a high-level view of the tasks that completed with success or errors. Double clicking on a task in this list will filter the log entries to logs generated by this task.

Actions List: In the lower left panel of Hot Folder View is a list of all actions in the Hot Folder. Double clicking on an action in this list will filter the log entries to logs related to the given action.

# Starting/Stopping Hot Folders

To start or stop a hot folder, right click on the hot folder in the Automate Panel and select "Start" or "Stop" respectively. You can also click on the start or stop icons in the upper-left corner of Hot Folder View for the given hot folder. For starting or stopping all hot folders, click on the dropdown icon in the upper-left corner of the Automate Panel and select "Start All" or "Stop All" respectively.

# How Hot Folders Work in Phoenix

There are two related concepts at the heart of hot folders: actions and resources.

Actions define what a hot folder does. Actions are described in an Actions XML file that is associated with the hot folder at setup time. This means the same list of actions is performed for each task coming through the hot folder.

Resources define the inputs and outputs of the actions. A Resources XML file is dropped into the hot folder to kick off new work when the hot folder is running. This file can contain job ID, paths of file(s) to import, presses, marks, export paths, preset names and more. Resources have a one-to-one relationship to the actions defined in the hot folder Actions XML file. Alternatively, resources can be built up programmatically using the scripting interface to support virtually any format as input to the hot folder.

For each action, there is a corresponding resource. In XML, the corresponding resource element for a given action always appends "-resource" to the action element name.

For example, in the Create Job action, the XML element name for the action is "<create-job>". The corresponding resource element name is "<create-job-resource>".

# Defining Resources

Resources for actions can be specified a number of different ways:

# Defined entirely in the Resources XML coming into the hot folder

For Import Product CSV action, the corresponding XML will look something like this:

Actions XML:

<import-product-csv id="4" />

Resources XML:

<import-product-csv-resource idref="4">
    <preset>MIS X Preset</preset>
    <path>/Users/user1/products.csv</path>
</import-product-csv-resource>

# Partially defined in the Actions XML file

This is useful when certain parameter(s) of an action's resource are static and others are dynamic. For example, if the same preset is always used in our Import Product CSV example but the input path changes, the corresponding XML can look something like this to avoid always specifying preset name in the Resources XML file:

Actions XML:

<import-product-csv id="4">
    <import-product-csv-resource>
        <preset>MIS X Preset</preset>
    </import-product-csv-resource>
</import-product-csv>

Resources XML:

<import-product-csv-resource idref="4">
    <path>/Users/user1/products.csv</path>
</import-product-csv-resource>

# Wholly defined in the Actions XML file itself

This is useful for actions that do not change parameters from job to job. For example if you are always using the same press, "B1 Press" on every job in the hot folder you can define the press in the Actions XML. At that point you do not need a corresponding resource in the Resources XML.

Actions XML:

<set-press id="2">
    <set-press-resource>
        <name>B1 Press</name>
    </set-press-resource>
</set-press> 

# Wholly or partially defined in Javascript code.

Using the scripting interface of hot folders, you can build up the list of resources programmatically, giving you more dynamic control and the ability to support file formats other than Resources XML such as PDF/AI/TIFF, CSV, etc. The returned list of resources is merged with any resources defined in the Actions XML in the same way as using the Resources XML directly, so only dynamic parameters need to be defined in your scripts.

// Create list of resources for this task
var resources = []; 
var createJob = new CreateJobResource(1);
createJob.id = filename;
createJob.notes = "Hot Folder " + date;resources.push(createJob);
…
return resources; 

# Combining Resources

When an action's resource is defined in both the Actions XML and in the incoming Resources XML, the resource is combined. In the example B) in the previous section, the hot folder will take the preset "MIS X Preset" defined in the Actions XML and the path from the Resources XML and perform the import action with both these parameters.

In cases where the same parameter is defined in the Actions XML and the incoming Resources XML, the Resources XML value is used. This is useful if you want to define default values in the Actions XML that can be optionally overridden on-the-fly in the Resources XML file.

# Mapping Resources to Actions

Since each action has a unique resource type, resources defined in incoming Resources XML files are simply mapped to the corresponding action in the Actions XML by default.

On top of this, you can optionally define IDs to correlate actions and resources. While not required, it is recommended to use IDs since mapping is explicit. Also, several actions can be defined more than once in an Actions XML file (e.g. Apply Mark action) so using IDs removes ambiguity in the mapping process.

For ID mapping, you start by assigning unique ID numbers to the actions you define in the Actions XML. Each action XML element has an optional "id" attribute for this purpose:

<create-job id="1">
...

Each resource XML element has an optional "idref" attribute that refers to the corresponding action's ID.

<create-job-resource idref="1">
…

# Actions XML Format

Actions XML file is a standards compliant XML 1.0 file. When not specified, the default character set is assumed to be UTF-8. Please refer to the Actions XML schema file included with this documentation for the formal definition of the Actions XML format.

All Actions XML files have the following structure where "action1" through "actionN" elements are replaced with valid actions defined in Section 4 below:

<?xml version="1.0" encoding="UTF-8"?>
<phoenix-actions version="1.0">
    <action1 id="1">...</action1>
    ... 
    <actionN id="N">...</actionN>
</phoenix-actions> 

Action Order: When automating jobs, actions are run in order from top to bottom. The first action in the Actions XML file must always be the Create Job action, i.e. <\create-job>.

File Type: The input file type in hot folders is an XML resource file by default, but you can configure the hot folder to expect a different format such as PDF or CSV. Most often this is used in conjunction with scripting to convert incoming files to a list of resources. See the Scripting section for more details. In these scenarios, you need to add the "file-type" attribute to the <\phoenix-actions> and specify the file extension of the input file. For example, if the incoming file is CSV, the <\phoenix-actions> element will look like this:

<phoenix-actions version="1.0" file-type="csv"> 

# Resources XML Format

As with Actions, the Resources XML file is a standard XML 1.0 file with default character set of UTF-8. Please refer to the Resources XML schema file included with this documentation for the formal definition of the Resources XML format.

All Resources XML files have the following structure where "action1-resource" through "actionN-resource" elements are replaced with valid resources defined in Section 4 below corresponding to the actions defined in the Actions XML for the given hot folder.

<?xml version="1.0" encoding="UTF-8"?>
<phoenix-resources version="1.0">
    <action1-resource idref="1">...</action1-resource>
    ...
    <actionN-resource idref="N">...</actionN-resource>
</phoenix-resources> 

# Output Paths in Resources

Output file paths for job save, export, and report actions can be an absolute path like:

<path>/Users/prepress/job-1023/imposed.pdf</path> 

If an Output Folder has been specified in the hot folder, relative paths are also supported. Relative paths will based off of the Output Folder. For example, if the Output Folder is /Users/prepress and the Export PDF action resource path is:

<path>job-1023/imposed.pdf</path> 

Then the PDF will be exported to the path:

/Users/prepress/job-1023/imposed.pdf 

# Library Names in Resources

Library names in resources such as presses or marks are folder based. If the library item being referenced is in a folder or sub-folder, the folders are listed with '/' path separator.

For example, the 'CAL 4C SLUR' mark is in the Calibration folder within the Defaults folder.

In the Apply Mark action resource XML, it's library name would look like this:

<apply-mark-resource>
    <name>Defaults/Calibration/CAL 4C SLUR</name>
</apply-mark-resource>  -->