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 run multiple custom actions at various points during the conversion process.

Custom actions can execute programs, scripts, or trigger events in other applications. Each stage can contain multiple custom actions executed in the order you specify. Conversion profiles store the custom actions with options for window visibility, execution order, and whether or not to wait for one action to complete before starting the next.

Type of Commands for Custom Actions

Commands can be executables (.exe), batch files (.bat), or commands (.com). We provide several batch files for typical tasks such as moving files and renaming files or file extensions. You can also create and use custom programs (executables) or batch files tailored to your workflow.

Environment variables and registry keys can make up all or part of the paths and parameters for any custom action. Environment variables and registry keys are helpful when setting up generic custom actions that work for all users when creating a custom printer setup or automating the printing.

Instead of running a command, custom actions can also signal an event. An event is similar to a raised flag on a mailbox that lets you know you have mail. A signaled event communicates with another program to inform it that a particular action has occurred. With events, you can send information about the different stages of file conversion to other applications and web services.

Custom Action Stages When Converting Documents

As our document-to-image/PDF conversion process relies on printing the file, we’ve adopted the term printing stages to describe the custom action 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 is started, will succeed or fail to be converted to an image or PDF, and finally, leaves the print queue. This print job analogy provides four stages in which you can add custom actions – Start of Job, On Success, On Failure, and End of Job.

• 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.
• On Success – The On Success stage occurs after the Image Printer has generated all images or PDF files from the print job. Use this stage to run a program that processes the created files. Optionally, you can pass the path to an auto-generated text file (pnf-[GUIID].txt) that contains a list of the created files as the last argument to the custom action. Each line in this text file is the full path to the file (or files) generated by the Image Printer. This text file can contain zero or more lines.
• On Failure – Custom actions set on this stage run when a print job has failed, such as when out of disk space. Custom actions here can also optionally pass the full path to a text file (pnf-[GUIID].txt) containing a list of the generated files appended as the last argument.
• End of Job – This stage occurs when the print job has finished processing, either with a created file or not. Custom actions added to this stage always run. This stage also has access to custom action variables with details about the result of the conversion.

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 the command runs.

A brief overview of the variables provided is below. Variables start with the characters ‘$(‘ and end with a ‘)‘. The text in between is the name of the variable and is case-sensitive.

• $(OutputFilePath) and $(OutputFilePathNoQuotes) – the full path to the created file.
• $(OutputDir) and $(OutputDirNoQuotes) – the output directory where the image printer created the file.
• $(JobStatus) – returns the success or failure state of the job.
• $(PrintedPageCount) – a count of the pages printed

Other macros are available for unique identifiers, user and computer names, 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.

Running Multiple Custom Actions

You can add more than one action to any stage. Actions will run in the order you choose. Each action has a wait mode that determines if it runs to completion before starting the next one. There are four wait modes:

• Do not wait
• Wait for completion
• Wait with exit code
• Show prompt to continue

If you need your custom actions to run sequentially, set your wait mode to Wait for completion so that each action finishes before starting the next. When using the generated pnf-[GUIID].txt file with the On Success or the On Failure command actions, the wait mode is always Wait for completion.

Adding a Custom Action to Process Converted Documents

After creating the images or PDF files, 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 customers 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

You can use either the On Success or the End of Job custom action stage to add a custom command to process the converted documents. An On Success custom action will only run when file creation succeeds. If it fails, the command does not run. To always run the action, use End of Job. Use the built-in variables, environment variables, registry keys, or text to pass information and parameters to your program.

If you are building a custom action executable or batch file from the ground up, take advantage of the On Success command, and the text file containing the list of created files is automatically passed to you to process the files as needed.

Starting with version 12.0.025, Image Printers allow you to use the command variables $(OutputFilePath) and $(OutputFilePathNoQuotes) to pass the output file path to custom actions, making it easy to integrate with existing tools.

For versions before 12.0.025, you must use the provided PNExec12.exe utility that processes our text file and calls your program with the path to the file and any other arguments needed.

Custom Actions Using Environment Variables

Custom actions can use Environment variables in the path to the command and also as the parameters passed to the command. Environment variables expand to their actual values when running the custom action. They are specified using the syntax %VARIABLE%. There are many well-known 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. If you use custom environment variables, you must define them on each computer where they will use them.

When you use environment variables in the path to the custom action, a preview shows, when possible, what the variable expands to. Environment variables let you access tools and other custom actions stored in different locations for different users as long as the environment variable contains the correct information 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 similar to using environment variables. They use the syntax of $[registry key], where the complete path to a valid registry key must appear inside the square brackets, including the value name as the last item.

The registry key needs to be a REG_SZ, or string key, containing text. The information, or value of the key, can be any text you need to use as a part or whole of the command path.

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 are whatever makes the most sense to you. Here, we are using CommandToRun and CommandParameters, but you could just as easily use ToolToRun and ToolArguments instead.

Use the $[registry key] syntax to set the command to run and the command parameters.

Signaling an Event from a Custom Action

You can use a custom action to signal an event to your application. Your application creates the event and waits for another application to signal the event. In this case, the Image Printer custom action opens and signals the event at the chosen custom action stage.

To add a custom action event, use the event syntax {EventName} as the command to run. The text between the curly braces is the name of the event that you want to signal. The curly braces tell us this is an event to signal and not a command to run. Event names can be up to 260 characters and are case-sensitive. Use the Global\ namespace prefix when creating events to share them between different processes.

Create a matching event using the same name in your application and wait inside your application for the signal from the custom action step when converting a document. What your application does when it receives the event is up to you.

Here, we use the event {Global\JobSucess} in an OnSuccess custom action to signal our application that the files are ready. The application creates an event of the same name, waits for the ready signal, and then processes the files.

Conclusion

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