Creating Document Conversion Processor Scripts

6 Creating Document Conversion Processor Scripts

Similar to other batch processors, the Document Conversion Processor allows customization of document conversion jobs using JavaScript (Nashorn). Here you learn how to create Document Conversion Processor scripts.

This chapter covers the following topics:

6.1 DocumentConverterContext Class

The DocumentConverterContext class contains properties relevant to the job being processed. An instance of this class is created before processing starts, and this instance is passed on to document conversion events at various stages of processing.

The following table lists the DocumentConverterContext fields. When a document conversion event is invoked, the corresponding DocumentConverterContext field is exposed to the event.

Property	Type	Description
cancel	Boolean	When the boolean value is set to true, it will cancel the operation being performed.
logger	Logger	An instance of `java.util.logging.Logger` that can be used to log additional entries.
docConverterJob	DocConverterJob	The current document conversion job being processed.
ble	BatchLockEntity	After a new batch is created, this property contains the Batch Lock entity for the batch.
activeDocument	DocumentEntity	The current active document being processed.
activeAttachment	DocumentEntity	The current active attachment being processed.
activePage	DocumentPageEntity	The current active page being processed.
externalProgramPath	String	The fully-qualified path to an external application that will be used to convert documents.
externalProgramCommandLine	String	The fully-qualified path to an external application that will be used to convert documents.
externalProgramSuccessCode	int	The value returned from an external program that indicates a successful conversion.
externalProgramMonitoringMethod	int	The monitoring method used to monitor the external program. The valid values are: 0 - Process duration 1 - Output file
externalProgramTimeout	int	When `externalProgramMonitoriingMethod` is 1 (Process duration), this value contains the number of minutes to allow the program to run before the program is considered to have timed-out due to a fault or hang. When this value is reached, the external program is terminated and an exception is thrown.
externalProgramDestFile	File	A File object representing the destination file that the external program will generate. Create and pass a File object in the script.

6.2 Document Conversion Processor Events

Document Conversion Processor scripts are JavaScript modules that enable you to customize the behavior of certain Document Conversion Processor events.

This section describes the following Document Conversion Processor events:

6.2.1 Initialize

The Initialize event signals that the document conversion processor job is in the initialization phase. The initialize method is invoked when the job starts. The DocumentConversionContext instance for the entire job is initialized at this point and passed into the method. An implementer can use this method to perform initialization tasks, such as creating database connections or creating temporary paths.

Syntax	Parameter
`public initialize(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.2.2 preProcessBatch

The preProcessBatch event occurs before a new batch is processed.

Syntax	Parameter
`public preProcessBatch(DocumentConverterContext ctx);`	DocumentConverterContext ctx

Associated DocumentConversionContext Properties

cancel: If set to true, the batch is not processed.
ble: At this point, this property will be initialized.

6.2.3 postProcessBatch

The postProcessBatch event occurs after the document conversion process is complete. An implementer can close database connections as well as cleanup temporary files and directories.

Syntax	Parameter
`public postProcessBatch(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.2.4 preProcessDocument

The preProcessDocument event occurs when the document, which is a part of the batch, is active for the conversion job. If there are multiple documents, this event is signaled for each document.

Syntax	Parameter
`public preProcessDocument(DocumentConverterContext ctx);`	DocumentConverterContext ctx

Associated DocumentConversionContext Properties

cancel: If set to true, the document is not processed.
ble: A reference to the associated BatchLockEntity.
activeDocument: A reference to the document that is about to be processed.

6.2.5 postProcessDocument

The postProcessDocument event occurs after the document, which is a part of the batch, has completed the conversion job. If there are multiple documents, this event is signaled for each document.

Syntax	Parameter
`public postProcessDocument(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.2.6 preProcessAttachment

The preProcessAttachment event occurs when the attachment, which is a part of the batch, is active for the conversion job. If there are multiple attachments, this event is signaled for each attachment.

Syntax	Parameter
`public preProcessAttachment(DocumentConverterContext ctx);`	DocumentConverterContext ctx

Associated DocumentConversionContext Properties

cancel: If set to true, the attachment is not processed.
ble: A reference to the associated BatchLockEntity.
activeAttachment: A reference to the attachment that is about to be processed.

6.2.7 postProcessAttachment

The postProcessAttachment event occurs after the attachment, which is a part of the batch, has completed the conversion job. If there are multiple attachments, this event is signaled for each attachment.

Syntax	Parameter
`public postProcessAttachment(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.2.8 preProcessPage

The preProcessPage event occurs when the page, which is a part of the batch or document, is about to be sent to a conversion job. If there are multiple pages, this event is signaled for each page.

Syntax	Parameter
`public preProcessPage(DocumentConverterContext ctx);`	DocumentConverterContext ctx

Associated DocumentConversionContext Properties

cancel: If set to true, the page is not processed.
ble: A reference to the associated BatchLockEntity.
activeAttachment: A reference to the page that is about to be processed.

6.2.9 postProcessPage

The postProcessPage event occurs after the page, which is a part of the batch or document, has completed the conversion job. If there are multiple pages, this event is signaled for each page.

Syntax	Parameter
`public postProcessPage(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.2.10 preInvokeExternalProcess

The preInvokeExternalProcess method is invoked right before an external conversion program is invoked.

Syntax	Parameter
`public preInvokeExternalProcess(DocumentConverterContext ctx);`	DocumentConverterContext ctx

Associated DocumentConversionContext Properties

cancel: If set to true, the page is not processed.
ble: A reference to the associated BatchLockEntity.
externalProgramPath: The path to the external program to execute.
externalProgramCommandLine: The command line to pass to the external program.
externalProgramSuccessCode: The integer value that represents a successful run when the external program terminates.
externalProgramMonitoringMethod: The method used to monitor the external program for hangs.
externalProgramTimeout: The duration in minutes that the external program is allowed to run before the program is terminated.
externalProgramDestFile: The output file to be generated by the external program; create and pass this File object in the script.

6.2.11 postInvokeExternalProcess

The postInvokeExternalProcess method is invoked soon after an external conversion program is completed.

Syntax	Parameter
`public postInvokeExternalProcess(DocumentConverterContext ctx);`	DocumentConverterContext ctx

6.3 Sample Document Conversion Processor Scripts

The section contains the following sample Document Conversion Processor scripts:

6.3.1 Sample Document Conversion Processor Script 1

The following script prints all events when a batch goes through conversion:

//doc conversion job script to print at the specific events
function initialize(event) {
    java.lang.System.out.println("initialize");
}
function preProcessBatch(event){
     java.lang.System.out.println("In preProcessBatch");
     java.lang.System.out.println("Batch name preProcessBatch: "+event.getBle().getBatch().getBatchName());
}
function postProcessBatch(event){
     java.lang.System.out.println("In postProcessBatch");
     java.lang.System.out.println("Batch name postProcessBatch: "+event.getBle().getBatch().getBatchName());
}
function preProcessDocument(event){
     java.lang.System.out.println("In preProcessDocument");
     java.lang.System.out.println("Title name preProcessDocument: "+event.getActiveDocument().getDocumentTitle());
}
function postProcessDocument(event){
     java.lang.System.out.println("In postProcessDocument");
}
function preProcessAttachment(event){
     java.lang.System.out.println("In preProcessAttachment");
     java.lang.System.out.println("Attachment name: "+event.getActiveAttachment().getDocumentTitle());
}
function postProcessAttachment(event){
     java.lang.System.out.println("In postProcessAttachment");
}
function preProcessPage(event){
     java.lang.System.out.println("In preProcessPage");
     java.lang.System.out.println("Page name: "+event.getActivePage().getDocumentEntity().getDocumentTitle());
}
function postProcessPage(event){
     java.lang.System.out.println("In postProcessPage");
}
function preInvokeExternalProcess(event){
     java.lang.System.out.println("In preInvokeExternalProcess");
}
function postInvokeExternalProcess(event){
     java.lang.System.out.println("In postInvokeExternalProcess");
}

6.3.2 Sample Document Conversion Processor Script 2

The following script cancels operation at the preProcessBatch event:

function initialize(event) {
    java.lang.System.out.println("initialize");
}
function preProcessBatch(event){
    var isCancel = true;
    event.setCancel(isCancel);
    java.lang.System.out.println("preProcessBatch and about to cancel operation.");
    java.lang.System.out.println("Batch name preProcessBatch: "+event.getBle().getBatch().getBatchName());
}
function postProcessBatch(event){
    java.lang.System.out.println("postProcessBatch - this line will not be printed.");
    java.lang.System.out.println("Batch name postProcessBatch: "+event.getBle().getBatch().getBatchName());
}

6.3.3 Sample Document Conversion Processor Script 3

The following script changes the batch name in the preProcessDocument event:

function preProcessDocument(event){
     java.lang.System.out.println("preProcessDocument batch-"+event.getBle().getBatch().getBatchName());
     event.getBle().getBatch().setBatchName("BatchInPreDocumentConv");
}
 
function postProcessDocument(event){
    java.lang.System.out.println("postProcessDocument batch-"+event.getBle().getBatch().getBatchName());
}