Hot Folder SDK

Introduction

The Hot Folder feature of PersonalEffect is an optional extra that can be licensed on uProduce server version 12.4 and later. Hot folders allow you to trigger document production, or perform other tasks, by simply dropping a file into a hot folder.

The Hot folder feature is implemented as a plugin so that developers can easily add Hot folder features to perform other tasks.

By default, there is only one Hot Folder plugin provided, and that plugin is designed to watch the hot folder for a data source file, and trigger production of a specific document using the data file added to the hot folder. This is a very common task for hot folders, but not the only thing that can be done.

A developer could easily create a plugin that watches for campaign packages added to the hot folder and automatically upload them to a uProduce Account. Or watch for PDF files that are then sent off to a digital asset management system that is totally outside of the XMPie environment.

The hot folder feature is designed to be very flexible and extensible so you can use it for many different tasks – and is limited only to your imagination and the abilities of the developer creating the plugin.

Technology overview

The hot folder plugin is designed in a way that decouples the plugin from the uProduce server so that the developer does not need to update the plugin each time there is a new uProduce version.

The developer needs to create:

• An ASP.NET Web User Control file that is loaded into the uProduce dashboard to allow an administrator to configure the settings needed for the custom plugin.

• An executable which uProduce calls when a file is added to the hot folder.

The executable can be created in any programming language that can compile an executable for Windows Server.

The user control and executable are added to specific folders on the uProduce server, and the custom plugin is registered in the SQL database. When an administrator creates a hot folder of the custom type, the custom user control is displayed in the dashboard to gather the required settings which are then stored in the database.

The uProduce server’s core software monitors the hot folder defined by the administrator. When a file is detected, it is moved to a working folder and arguments are passed to the custom executable to perform the required functions.

The executable is able to pass status information back to the uProduce server which is displayed to the user via the hot folder job center, and logging information which is available in the XMPieLogs folder.

Accessing the SDK

XMPie provides a Hot Folder SDK that includes a sample Visual Studio solution that demonstrates how to create a Hot Folder Worker using C#.

Customers who have purchased the Hot Folder feature can request the Hot Folder SDK from XMPie Support.

SDK walkthrough

The Hot Folder SDK includes a Microsoft Visual Studio solution that contains a sample C# Console project that demonstrates:

• Reading and using the arguments passed to the executable.

• Logging messages to the uProduce server logs.

• Accessing the uProduce REST API to create and submit a job ticket.

• Update the Hot folder job status in the dashboard.

• Handle different data file encoding.

  
  Files provided in the Hot Folder SDK's Visual Studio Solution

• The DashboardConfig folder contains:

  • A sample ASP.NET Web User Control that is loaded into the dashboard when creating or editing the settings of a hot folder. Depending on the purpose of your plugin, you will need to capture different settings.

    
    The ASP.NET Web User Control is loaded into this area when creating or editing Hot Folder Settings

  • An SQL script used to register the custom plugin to the uProduce SQL database. Note: the script is prepared with the name of the sample executable and the file extensions that it will accept to process. If you are creating an executable with a different name, or that expects different file types, you will need to edit the file to suit your needs.

• Logger.cs is an interface to the uProduce logging mechanism.

• Program.cs is the main entry point for the executable. Here you will find examples of how to:

  • Parse the arguments passed to the executable

  • Use the uProduce Logger with different log levels

    Copy

    // getting the input arguments
    If (args == null || args.Length != 4)
    {
        Logger.LogError("Invalid number of arguments");
        return;
    }
    string fileId = args[0].Trim('\"', '\'', ' ', '\t', '\n', '\r');
    string filePath = args[1].Trim('\"', '\'', ' ', '\t', '\n', '\r');
    string apiToken = args[2].Trim('\"', '\'', ' ', '\t', '\n', '\r');
    string apiBaseUrl = args[3].Trim('\"', '\'', ' ', '\t', '\n', '\r');
    
    Logger.LogMessage("Run with file id {0}, path {1}, api token {2}, api base url {3}", 
                      fileId, filePath, apiToken, apiBaseUrl);

  • Access the uProduce REST API to update the status shown to the user in the Hot Folder Job Center

    Copy

    // creating a uProduce API client
    uProduceAPIs.Actions apiClient = CreateAPIsClient(apiBaseUrl, apiToken);
    
    // updating the file status, and get its full information
    uProduceAPIs.HotFolderFileExtended hotFolderFile = new uProduceAPIs.HotFolderFileExtended();
    hotFolderFile.Status = uProduceAPIs.HotFolderFileStatus.Processing;
    if (!UpdateFileStatus(apiClient, fileId, ref hotFolderFile))
        return;

  • The hot folder settings are read from the REST API and deserialized to use in the executable.

    Copy

    try
    {
        jobTicket = JsonConvert.DeserializeObject<uProduceAPIs.JobTicket>(
               hotFolderFile.FullHotFolder.Type.Properties["JobTicket"].ToString());
    }
    catch (Exception ex)
    {
        hotFolderFile.Status = uProduceAPIs.HotFolderFileStatus.Failed;
        hotFolderFile.Info = string.Format(
                "Failed to read base job ticket - {0}", GetMostRelevantMessage(ex));
        Logger.LogError("File {0}: {1}", fileId, hotFolderFile.Info);
        UpdateFileStatus(apiClient, fileId, ref hotFolderFile);
        return;
    }

  • The example then goes on to create a JobTicket to submit a document to production. In the case of your hot folder plugin, you will need to use the settings to perform whatever actions you want, and update the dashboard job status as needed.

  Deployment

  1. Compile the Visual Studio solution:

     1. Open the SampleHotFolderWorker.sln and compile it with a release build.

  2. Register the plugin type in the XMPDB2 database:

     1. Open SQL Server Management Studio.

     2. Connect to the uProduce database server.

     3. Open the file SampleHotFolderWorker.sql.

     4. Run the query.

  3. Register the UI Dashboard configuration:

     1. Go to uProduce dashboard folder X:\XMPie\XMPieDashboard\.

     2. Edit the file PrecompiledApp.config, and change updatable from false to true if needed.

     3. If you changed the PrecompiledApp.config file, run iisreset.

     4. Copy the files:

        • SampleHotFolderWorker.ascx

        • SampleHotFolderWorker.ascx.cs

     5. Paste the files in: X:\XMPie\XMPieDashboard\Settings\HotFolderTypes\.
        (In configurations with multiple director servers, the user controls should be copied to all directors.)

  4. Copy the binaries you compiled with Visual Studio to the uProduce server:

     1. Go to uProduce binaries folder X:\XMPie\XMPieExec\HotFolderModules\.

     2. Create a new folder named SampleHotFolderWorker.

     3. Copy the compiled binaries from your VS Solution, found under SampleHotFolderWorker\bin\x64\Release\.

     4. Paste the binaries into that new folder.
        (In configurations with multiple extension servers, the binaries should be copied to all production extensions and any director servers that also do production.)

  5. Create a new hot folder in the uProduce Dashboard.

     1. Browse to the Dashboard and login as an admin user.

     2. In the Settings area, create a new hot folder using the Sample Hot Folder Worker as the selected type.

  6. Test it.

uProduce server upgrades

As mentioned above, it is not necessary to update the hot folder plugin for uProduce server upgrades.

However, upgrades (and also repairs) to the uProduce server can remove custom plugins from the XMPieExec and XMPieDashboard folders.

Therefore, it is recommended to:

• Keep a copy of the custom files outside of the XMPie folders in case they need to be deployed again after an upgrade or repair.

• After each uProduce upgrade or repair, check the executable, user controls, PrecompiledApp.config file and SQL database to confirm that your custom plugin is still configured correctly.

Video tutorials

Introduction to uProduce Hot Folders

Creating and using a Hot Folder

Developing a Hot Folder Plugin