# Hotfolder Scripting

Hot folders automation includes an optional scripting interface, providing an unprecedented amount of customization during automation. Scripting is done in the popular JavaScript language.

There are several uses for scripting in hot folders. Below are some of the more common examples:

• Support input files with formats other than the standard Resources XML format described in this document. For example, another XML format, CSV spreadsheet, or other text-based format containing information about the job to be automated.
• Waiting for a certain number of input files to come into the hot folder or a certain duration before performing actions.
• Analyzing the results of ganging tools to remove layouts that do not meet certain criteria such as sheet usage or waste and moving products from these layouts back into the input file to be ganged with more incoming files.
• Customized notification when a job has succeeded or failed. Provided utility methods in the scripting environment make it easy to send email alerts or record error details in local files.
• Convert image files to PDFs or breaking up large PDFs into tiles using the PDFUtils utility methods.

# Scripting Hooks

Hot folder scripting has three entry points that you can implement to add custom behavior to hot folders: onStart(), onSuccess(), and onFail(). All three functions are optional, but at least one of these functions needs to be implemented in a script when it is loaded into a hot folder.

# onStart()

Description: Initial hook when a file comes into the hot folder. This function is called before any actions are processed to convert the incoming file into a list of resource objects needed by the actions in the hot folder, perform tiling or image to PDF conversion, delay processing based on a custom trigger event, and more. Trigger Event: Called when a file comes into the hot folder with file extension matching the file-type attribute in <phoenix-actions> element, or .xml if file-type is not specified. Arguments:

• state (FolderState): Hot folder state
• inputs (InputFile List): List of InputFiles
• Return Type: A JavaScript array of resource objects needed by actions. These are the same resource objects that are normally represented in Resources XML files. Note: As mentioned in the Actions XML Format section, by default hot folders watch for files with the .xml extension. If the file format you are processing in onStart() does not have a .xml extension you need to specify the expected extension in the Actions XML file in the <phoenix-actions> element attribute called "file-type". For example, if the incoming file in the hot folder is a CSV file with extension .csv, the Actions XML needs to specify the csv extension:

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

# onSuccess()

Description: Hook called when all actions in the hot folder have completed successfully. This hook is useful for sending notification emails, adding custom logging, moving per-layout export files into folders organized by presses/stocks, moving products in sub-par layouts back into the input folder, and more. Trigger Event: All actions in the hot folder have completed successfully for a given task. Arguments:

• state (FolderState) – Hot folder state (see section 3.5.2)
• inputs (InputFile List) -List of InputFiles (see section 3.5.3)
• job (JobEntity) – Job object representing detailed information about the job that completed. Job entity format is the same as the JSON job report. You can find the formal schema definition in this guide under the Schemas folder. Return Type: None

# onFail()

Description: Hook called when an error occurred during hot folder processing. This hook is useful for sending notification emails or recording the event by other means. Trigger Event: An error occurred during processing for a given task. Arguments:

• state (FolderState) – Hot folder state (see section 6.2)
• inputs (InputFile List) -List of InputFiles (see section 6.3)
• report (ErrorReport) – Error report listing errors and warnings that occurred during task processing. Error Report format formal schema definition in this guide under the Schemas folder. Return Type: None

# Classes

# FolderState Class

# InputFile Class

Input file class representing a single input file in a hot folder

# Mail Class

# Document Class

Document class representing a PDF document

# Page Class

Page class representing a page of PDF document

# Rect Class

Input file class representing a single input file in a hot folder

# Utility Classes

Several utility classes are provided within the scripting environment for moving and parsing files, working work PDFs, sending email notifications and more.

# JobUtils

# FileUtils

# MailUtils

# PDFUtils

# GeomUtils

# Example Hotfolder Scripts

Below you'll find some example scripts and snippets to help you understand how scripting works, as well as help with some common scripting needs

# Find a product's custom property

You can access a product's default properties fairly simply, by using product.index or product.name. If you want to access a custom property, however, they are stored in a properties list inside of the product. An easy way to find your property is to loop through the custom properties and return the value if the property name matches the one you're looking for:

// Grab first product to find product properties
// required for file naming. Could place this in 
// a loop to look through all products

var product = job.products.get(0);

// Loop through all of this product's properties, 
// saving StoreNum property values
for (var i=0; i<product.properties.size(); i++) {
    var property = product.properties.get(i);

    if (property.name == "StoreNum"){
        var store = property.value;
    }
}