Add Custom Actions When Converting Documents

Converting documents and images from one format to another is often part of an overall document workflow. It is usually just one part of a sequence of steps and custom actions to automate converting, processing, and storing documents. Your workflow may need to start an application before conversion begins. More common is the need to pick up the created files for further processing. Another common step is creating trigger files that other applications look for to know when to start a particular task.

With PEERNET’s TIFF Image Printer, Raster Image Printer and PDF Image Printer you can add multiple custom actions that occur at different stages of conversion. A custom action can run another program or a batch or script file or it can signal an event to another program. Each stage has a separate collection of custom actions that run-in order. Each action runs to completion before the next action starts. Custom actions are stored in conversion profiles, along with other information

Type of Commands for Custom Actions

Commands can be batch files (.bat), executables (.exe) or command (.com). The image printer software provides batch files for some common tasks such as moving and renaming files or file extensions.  You can also create and use your own custom programs (executables) or batch files.

Environment variables and registry keys can make up all or part of the paths and parameters for the custom actions. Environment variables and registry keys are useful when setting up generic custom actions that work for all users, when creating custom printer setups, or automating the printing.

Instead of running a command, you can also use custom actions to signal an event. An event is similar to a raised flag on a mailbox that lets you know you have mail. A signaled event lets another program know that a particular action has occurred. With events, you can communicate information about the different stages of file conversion to your own programs.

Custom Action Stages When Converting Documents

As the document to image or PDF conversion takes place by printing the file, we also refer to the custom action stages as printing stages. The document, when sent to a printer, is a print job. Printers hold on to the submitted print jobs in a print queue. Each print job starts, is converted to an image, or fails, and then leaves the print queue. This provides four stages where you can add custom actions – Start of Job, Print Job Succeeded, Print Job Failed and End of Job.

1. Start of Job

This stage is when the document, now a print job, enters the print queue. The custom action entered in this stage will run every time a print job enters the print queue. One use for this custom action is to ensure a single-instance program that processes the created files is running.

2. Print Job Succeeded

At this stage all the images or PDF files have been successfully created. Any custom action run in this stage also receives the full path to a text file (pnf-[GUIID].txt) containing a list of the generated files as the last argument in additional to any specified arguments provided in the custom action. This text file can contain zero or more lines. Each line is the full path to a file generated by the Image Printer. Use this stage to pass the list of created files to your own programs for processing.

3. Print Job Failed

Custom actions set on this stage run when a print job has failed, such as when out of disk space. Custom actions here also have the full path to a text file (pnf-[GUIID].txt) containing a list of the generated files appended as the last argument.

4. End of Job

This stage occurs when the print job is removed from the print queue. Custom actions in the End of Job stage always run, no matter if the print job succeeds or fails.

Custom Action Variables

These variables pass information from the conversion process to a custom action as arguments in the parameters list. They expand to their actual values when running the command. A brief overview of the variables provided is below. Variables start with the characters ‘$(‘ and end with ‘)’; the text in between describes the variable and is case sensitive.

To pass the output directory as a parameter to a command you would use $(OutputDir) or $(OutputDirNoQuotes). Query the success or failure state of the job using $(JobStatus), while $(PrintedPageCount) will give you a count of the pages printed. Other macros are available for unique identifiers, print job information and date and time of conversion. You can find a detailed listing in the Run Commands Macros section of the online user guide.

Adding a Custom Action to Process Converted Documents

After the images have been converted, what do you do with them? With custom actions the answer is anything you want or need to do. Some of the more common tasks that our customer have done are the following, to give you an idea:

• Upload them to a document storage system
• Update a database
• Send a message to a web service
• Create index or trigger files in the format needed for pickup by another process

To process the converted documents add your custom action to the Print Job Succeeded stage. You can add more than one action. Actions run to completion and in the order you choose. Action run in this stage always pass a text file listing the full path of each of the created file(s) as the last argument to the command.

If you are building a custom action executable or batch file from the ground up take advantage of the text file containing the list of created files that is passed to process the files as needed. Use the built-in variables, environment variables, registry keys or text to pass in other information and parameters.

If you have existing applications or command line tools that wants the path to the file to process, a utility has been provided that processes our text file and calls your program with the path to the file, and any other arguments needed. Two new custom action variables are available to specify the filename in the argument list, $(OutputFilePath) and $(OutputFilePathNoQuotes).

Custom Actions Using Environment Variables

Custom actions can use Environment variables in the path to the command and in the parameters passed to the command. Environment variables expand to their real when running the custom action. They are specified using the syntax %VARIABLE%. There are many well know system variables, %USERPROPFILE%, %TEMP% and %USERNAME% to list a few.

You can also create and use your own system or user environment variables. Variables must be spelled correctly but are not case sensitive. Custom environment variables need to be created on each computer where they are used.

Use your environment variable in the path to the custom action. A preview shows what the variable expands to when possible. This lets you access tools and other custom actions stored in different locations for different users, as long as the environment variable for the user is set to the correct path for that user. You can also use environment variables in the parameter list.

Custom Actions Using Registry Keys

Using a registry key in a custom action is very similar to using environment variables. They have their own syntax of $[registry key] where registry key is a complete path to a valid registry key. The information in the registry key is up to you. Take care when deciding where in the registry to store the key; anyone running a conversion with the custom action will need permission to read the key.

The names used for the keys can be whatever what makes the most sense to you. Here we are using ConmmandToRun and CommandParameters but you could use Utility and Arguments instead. The information, or value of the key can be any text you need to inject into the command or its parameters. It does need to be a REG_SZ, or string key containing text.

Use the $[registry key] syntax to set the command to run and the command parameters. The complete path to a valid registry key value must appear inside the square brackets, including the value name as the last item.

Signaling an Event from a Custom Action

A custom action can signal an event to your own application. Your application creates and waits on the events, the driver only opens and signals them. To signal to your application that your files are ready to process use an event as the custom action in the Print Job Succeeded stage.

Add a custom action event using the special syntax: {EventName}, where EventName is the name of the event that you want to signal. Create a matching event in your application that waits for the signal from the custom action step when converting a document. The curly braces tell us this is an event, and not a command to run.

Event names can be up to 260 characters and are case sensitive. Use the global namespace prefix, Global\ when creating events.

Conclusion

Custom actions provide a lot of flexibility when integrating document conversion into your day to day document management. Built-in commands, calling external tools for other applications and writing your own customized tools when necessary allow you to make PEERNET’s TIFF Image Printer, Raster Image Printer and PDF Image Printer work for you.