IDocumentConverterScript interface definition
The IDocumentConverterScript script interface extends the functionality of IReRouteScript script. IDocumentConverterScript exposes DocumentConverter() API along with ReRoute() API.
Following is the definition of the IDocumentConverterScript interface.
public interface IDocumentConverterScript : IReRouteScript
{
/// <summary>
/// DocumentConverter API called by KIC.
/// </summary>
/// <param name="message">The incoming Message</param>
/// <param name="converter">IDocumentConverter interface object used to Convert/Combine/Unzip the desired documents</param>
/// <returns>The result of Convert/Combine/Unzip operation.</returns>
ConversionResult DocumentConverter(Message message, IDocumentConverter converter);
}
Description of the parameters.
Parameter |
Description |
---|---|
Message |
The incoming Message. |
Converter |
The IDocumentConverter interface object used to convert/combine/unzip the desired documents. |
Following is the definition of the IDocumentConverter API.
/*
* IDocumentConverterScript interface extends the functionality of IReRouteScript script.
* IDocumentConverterScript exposes DocumentConverter() API along with ReRoute() API.
* Using the implementation of IDocumentConverter interface in DocumentConverter() API,
* we can acheive the following functionality:
* 1) Combine Body of a message with individual Attachments. (Check AppendBodyToAttachments_FR7043.cs in KCSImportScriptingSample.zip)
* 2) Convert any Documents to PDF and/or Tiff. (Check SampleDocumentConverterScript.cs in KCSImportScriptingSample.zip)
* 3) Concatenate individual PDFs to a single PDF/A document.(Check SampleDocumentCombineScript.cs in KCSImportScriptingSample.zip)
* 4) Extract Zipped archives.(Check SampleUnzipScript.cs in KCSImportScriptingSample.zip)
* */
/// <summary>
/// IDocumentConverter Interface definition.
/// </summary>
public interface IDocumentConverter
{
/// <summary>
/// This API is used to convert any Document to PDF and/or Tiff. For sample usage refer SampleDocumentConverterScript.cs in KCSImportScriptingSample.zip.
/// </summary>
/// <param name="output">If the operation is successful, output contains the converted document.</param>
/// <param name="input">The document to be converted to TIFF or PDF.</param>
/// <param name="destinationName">The name of the destination to be used to read the conversion settings.</param>
/// <returns>The result of the conversion operation.</returns>
ConversionResult Convert(out List<Attachment> output, Attachment input, string destinationName);
/// <summary>
/// This API is used to convert a List of input Documents to PDF and/or Tiff. For sample usage refer SampleDocumentConverterScript.cs in KCSImportScriptingSample.zip.
/// </summary>
/// <param name="output">If the operation is successful, output contains the converted documents.</param>
/// <param name="input">The documents to be converted to TIFF or PDF.</param>
/// <param name="destinationName">The name of the destination to be used to read the conversion settings.</param>
/// <returns>The result of the conversion operation.</returns>
ConversionResult Convert(out List<Attachment> output, List<Attachment> input, string destinationName);
/// <summary>
/// This API is used to convert a List of input Document to PDF and/or Tiff. For sample usage refer SampleDocumentConverterScript.cs in KCSImportScriptingSample.zip.
/// </summary>
/// <param name="output">If the operation is successful, output contains the converted documents.</param>
/// <param name="input">The documents to be converted to TIFF or PDF.</param>
/// <param name="converstionOptions">The options to be used for conversion.</param>
/// <returns>The result of the conversion operation.</returns>
ConversionResult Convert(out List<Attachment> output, Attachment input, DocumentConversionOptions converstionOptions);
/// <summary>
/// This API is used to convert a List of input Documents to PDF and/or Tiff. For sample usage refer SampleDocumentConverterScript.cs in KCSImportScriptingSample.zip.
/// </summary>
/// <param name="output">If the operation is successful, output contains the converted documents.</param>
/// <param name="input">The documents to be converted to TIFF or PDF.</param>
/// <param name="converstionOptions">The options to be used for conversion</param>
/// <returns>The result of the conversion operation.</returns>
ConversionResult Convert(out List<Attachment> output, List<Attachment> input, DocumentConversionOptions converstionOptions);
/// <summary>
/// This API is used to Unzip/Extract compressed files.
/// </summary>
/// <param name="output">The list of files in the compressed file.</param>
/// <param name="input">The compressed file.</param>
/// <param name="options">The options to be used for extraction.</param>
/// <returns>The result of the extraction operation.</returns>
ConversionResult Extract(out List<Attachment> output, Attachment input, DocumentExtractOptions options);
/// <summary>
/// This API is used to concatenate multiple PDF files into a single PDF or PDF/A file.
/// </summary>
/// <param name="output">The resultant concatenated PDF file.</param>
/// <param name="input">The list of individual PDF files to be concatenated.</param>
/// <param name="options">The options to be used for the concatenate operation.</param>
/// <returns>The result of the concatenation operation.</returns>
ConversionResult CombineBinaries(out Attachment output, List<Attachment> input, DocumentCombineOptions options);
/// <summary>
/// This API is used to concatenate multiple PDF files into a single PDF or PDF/A file.
/// </summary>
/// <param name="output">The resultant concatenated PDF file.</param>
/// <param name="body">The body of the message to be concatenated.</param>
/// <param name="input">The list of attachments to be concatenated.</param>
/// <param name="options">The options to be used for the concatenate operation.</param>
/// <param name="appendBodyFirst">True, for body first and attachments. False, for attachments first and body.</param>
/// <returns></returns>
ConversionResult CombineBodyWithAttachments(out List<Attachment> output, Attachment body, List<Attachment> input, DocumentCombineOptions options, bool appendBodyFirst);
/// <summary>
/// This API is used to get the Document Conversion Options configured in the specified Destination.
/// </summary>
/// <param name="conversionOptions">The Document Conversion Options encapsulated in DocumentConversionOptions object</param>
/// <param name="destinationName">Destination Name to be used to retrieve the Document Conversion Options </param>
/// <returns>The result of the operation</returns>
ConversionResult GetConversionOptionsFromDestination(out DocumentConversionOptions conversionOptions, string destinationName);
}
DocumentConverter () API details
Method name |
Signature |
Description |
---|---|---|
Convert |
ConversionResult Convert(outList<Attachment> output, Attachment input, string destinationName); |
Converts a document to PDF and/or TIFF on the basis of configuration in the destination defined by the destinationName parameter. |
Convert |
ConversionResult Convert(out List<Attachment> output, List<Attachment> input, string destinationName); |
Converts a list of input documents to PDF and/or TIFF on the basis of configuration in the destination defined by the destinationName parameter. |
Convert |
ConversionResult Convert(out List<Attachment> output, Attachment input, DocumentConversionOptions converstionOptions); |
Converts a list of input documents to PDF and/or TIFF on the basis of settings defined in the converstionOptions parameter. |
Convert |
ConversionResult Convert(out List<Attachment> output, List<Attachment> input, DocumentConversionOptions converstionOptions); |
Converts a list of input documents to PDF and/or TIFF on the basis of settings defined in the converstionOptions parameter. |
Extract |
ConversionResult Extract(out List<Attachment> output, Attachment input, DocumentExtractOptions options); |
Unzips or extracts the compressed files and extracts portfolio PDF file. |
CombineBinaries |
ConversionResult CombineBinaries(out Attachment output, List<Attachment> input, DocumentCombineOptions options); |
Concatenates multiple PDF documents into a single PDF or PDF/A document. The Options parameter defines the settings to perform the combine operation. This is only applicable for PDF documents.
|
CombineBodyWithAttachments |
ConversionResult CombineBodyWithAttachments(out List<Attachment> output, Attachment body, List<Attachment> input, DocumentCombineOptions options, bool appendBodyFirst); |
Concatenates the body of a message to each attachment in the message.
|
GetConversionOptionsFromDestination |
ConversionResult GetConversionOptionsFromDestination(out DocumentConversionOptions conversionOptions, string destinationName); |
Reads the document conversion options specified in the destination configuration and populates the DocumentConversionOptions object. |
Class properties
.Net SDK class name |
Property name |
Property type |
Description and possible values |
---|---|---|---|
ConversionResult |
Code |
Integer |
Sets or gets the error code of the conversion operation. '0' is returned for successful operation. Any other value implies a failed operation. |
ConversionResult |
Message |
String |
Contains the error message of a failed conversion operation. This remain empty for a successful conversion. |
ConversionDetails |
imageQuality |
Integer |
Sets the image quality for conversion. The value '100' is set for no compression. This is only applicable for grayscale and color TIFF images. Compression may impact image quality.
|
ConversionDetails |
imageResolution |
Integer |
Gets or sets the resolution of the output image. This corresponds to image DPI setting and is deduced from an Enum. The possible values are 200 and 300. Default is 200. |
ConversionDetails |
smoothFlags |
Integer |
Gets or sets a value for smoothing flags. Use these flags to configure the JPEG quality of the PDF to TIFF conversion. The possible values are:
This parameter contains the result of an OR operation performed on the selected options. |
ConversionDetails |
renderFlags |
Integer |
Gets or sets the value for rendering flag. The possible value is PDPageNoDither = 0x40000000 |
ConversionDetails |
scaleTo |
Enum |
Gets or sets the scaling property to use for conversion. The possible values are:
|
ConversionDetails |
imageCoding |
Integer |
Gets or sets the output color. The possible values are:
Default is 3. |
ConversionDetails |
isALCFlatteningEnabled |
bool |
Gets or sets a value to use Adobe Life Cycle Server for flattening XFA forms. By default, flattening of XFA forms is disabled. |
ConversionDetails |
isPdfNormalationEnabled |
bool |
Gets or sets a value to normalize the document to PDF/A. By default, normalization is disabled. |
ConversionDetails |
PDFACompliance |
Enum |
Gets or sets a value to convert PDF documents to one of the PDFA type format. The possible values are:
This is only applicable when convert to PDF option is enabled. |
ConversionDetails |
SetPasswords |
SecureString |
Sets the passwords for unlocking password protected PDF files. |
ConversionDetails |
GetPasswords |
SecureString |
Gets the passwords for unlocking password protected PDF files. |
DocumentCombineOptions |
combineTo |
Enum |
Gets or sets a value to combine the documents. This is only applicable for PDF documents. |
DocumentCombineOptions |
WaitTimeSec |
Integer |
Gets or sets the wait time to complete the combine operation. Default is 120 seconds. |
DocumentCombineOptions |
conversionDetails |
ConversionDetails |
The ConversionDetails object contains the option to use for document conversion. |
DocumentConversionOptions |
Tif |
Integer |
Gets or sets the value to convert documents to TIFF or not. The possible values are:
|
DocumentConversionOptions |
|
Integer |
Gets or sets a value to convert to PDF or not. The possible values are:
|
DocumentConversionOptions |
WaitTimeSec |
Integer |
Gets or sets a value indicating the wait time to complete the combine operation. |
DocumentConversionOptions |
WaitTimeSecSpecified |
bool |
Gets or sets a value to identify whether the WaitTimeSec property is set or not. |
DocumentConversionOptions |
ConversionDetails |
ConversionDetails |
The ConversionDetails object contains the options to convert the document. |
The following features are available using the implementation of IDocumentConverterScript interface in DocumentConverter() API:
-
Append body of a message to individual attachments
-
Extract zipped archive files
-
Convert documents to PDF and/or TIFF format
-
Concatenate multiple PDF documents to a single PDF/A document
Append message body to attachments
This feature appends the body of a message to each message's attachment after the conversion. That is, each converted attachment has the message body appended.
Sample code for using this function:
public class AppendBodyToAttachments_FR7043 : IDocumentConverterScript
{
public ConversionResult DocumentConverter(Message message, IDocumentConverter converter)
{
ConversionResult result = new ConversionResult();
if (converter != null)
{
List<Attachment> combinedAttachments = null;
DocumentCombineOptions options = new DocumentCombineOptions();
Attachment body = message.BodyAttachments.Find(att => att.IsBody == true && att.Extension.ToUpper() == "PDF");
// Call CombineBodyWithAttachments API to combine Body to all the attachments.
result = converter.CombineBodyWithAttachments(out combinedAttachments, body, message.BodyAttachments, options, false);
if (result.Code == 0)
{
message.BodyAttachments = combinedAttachments;
}
}
return result;
}
public eMessageScriptCode ReRoute(Message message, object extension)
{
return eMessageScriptCode.Other;
}
}
To enable this feature, do the following:
-
Copy the script file AppendBodyToAttachments_FR7043.cs from the KCSImportScriptingSample.zip file. Default path:
C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample
-
Paste this script file to a local path. In Additional settings tab of KC Plug-In Destination configuration, configure Rerouting\Document conversion script path field to browse the AppendBodyToAttachments_FR7043.cs file.
-
Ensure that the Convert to option is set to PDF in the Import settings tab.
-
Restart the KC Plug-in service.
Extract zip files
This feature extracts the zip files, that is, any email attachments or files in zip format are extracted. The extracted files can be converted to PDF or TIFF format.
Sample code for using this function.
public class SampleUnzipScript : IDocumentConverterScript
{
/// <summary>
/// This method is used to Extract Zipped archives.
/// </summary>
/// <param name="message">The message to be imported into KC</param>
/// <param name="converter">The Document Converter Interface object</param>
/// <returns></returns>
public ConversionResult DocumentConverter(Message message, IDocumentConverter converter)
{
ConversionResult result = new ConversionResult();
if (converter != null)
{
List<Attachment> unzippedAttachments = null;
DocumentExtractOptions options = new DocumentExtractOptions();
foreach (Attachment att in message.BodyAttachments)
{
if (att.Extension.ToLower() == "zip" || att.ContentType.ToLower() == "application/octet-stream")
{
result = converter.Extract(out unzippedAttachments, att, options);
if (result.Code == 0 && unzippedAttachments != null && unzippedAttachments.Count > 0)
{
message.BodyAttachments.AddRange(unzippedAttachments);
}
}
}
return result;
}
return result;
}
public eMessageScriptCode ReRoute(Message message, object extension)
{
return eMessageScriptCode.Other;
}
}
To enable this feature, do the following:
-
Copy the script file SampleUnzipScript.cs from the KCSImportScriptingSample.zip file. Default path:
C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample
-
Paste this script file to a local path. In Additional settings tab of KC Plug-In Destination configuration, configure Rerouting\Document conversion script path field to browse the SampleUnzipScript.cs file.
-
Restart the KC Plug-in service.
Convert documents to PDF or TIFF
This feature converts the files to PDF or TIFF formats. If the PDF files are converted to PDF format, you can concatenate these files.
Sample code for using this function.
public class SampleDocumentConverterScript : IDocumentConverterScript
{
/// <summary>
/// This method is used to Convert dicuments to Tiff/PDF
/// </summary>
/// <param name="message">The message to be imported into KC</param>
/// <param name="converter">The Document Converter Interface object</param>
/// <returns></returns>
public ConversionResult DocumentConverter(Message message, IDocumentConverter converter)
{
ConversionResult result = new ConversionResult();
if (converter != null)
{
List<Attachment> convertedAttachments = null;
DocumentConversionOptions options = new DocumentConversionOptions();
options.ConversionDetails = new ConversionDetails();
// To Convert documents to Tiff or PDF, configure the required options below.
// Configuring Both PDF and Tif conversion.
options.Pdf = options.Tif = 1;
result = converter.Convert(out convertedAttachments, message.BodyAttachments, options);
if (result.Code == 0 && convertedAttachments != null && convertedAttachments.Count > 0)
{
message.BodyAttachments.AddRange(convertedAttachments);
}
}
return result;
}
public eMessageScriptCode ReRoute(Message message, object extension)
{
return eMessageScriptCode.Other;
}
}
To enable this feature, do the following:
-
Copy the script file SampleDocumentConverterScript.cs from the KCSImportScriptingSample.zip file. Default path:
C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample
-
Paste this script file to a local path. In Additional settings tab of KC Plug-In Destination configuration, configure Rerouting\Document conversion script path field to browse the SampleDocumentConverterScript.cs file.
-
Ensure that the Import original content option is selected in the Import settings tab.
-
Restart the KC Plug-in service.
Concatenate PDF files
This feature concatenates individual PDF documents to a single PDF/A document. The output contains individual PDF documents along with one concatenated PDF/A document.
Sample code for using this function:
public class SampleDocumentCombineScript : IDocumentConverterScript
{
public ConversionResult DocumentConverter(Message message, IDocumentConverter converter)
{
ConversionResult result = new ConversionResult();
if (converter != null)
{
Attachment combinedAttachment = null;
DocumentCombineOptions options =
new DocumentCombineOptions
{
/* Setting CombineTo to PDF.*/
combineTo = CombineOptionsCombineTo.PDF,
WaitTimeSec = 120,
conversionDetails = new ConversionDetails()
};
// Enabling PDF normalization and ALC flattening.
options.conversionDetails.isALCFlatteningEnabled = true;
options.conversionDetails.isPdfNormalationEnabled = true;
result = converter.CombineBinaries(out combinedAttachment, message.BodyAttachments, options);
if (result.Code == 0 && combinedAttachment != null)
{
// Uncomment below line To replace all the files and import only the combined attachment
//message.BodyAttachments.Clear();
// To add the combined Attachment to the list of files imported
message.BodyAttachments.Add(combinedAttachment);
}
}
return result;
}
public eMessageScriptCode ReRoute(Message message, object extension)
{
return eMessageScriptCode.Other;
}
}
To enable this feature, do the following:
-
Copy the script file SampleDocumentCombineScript.cs from the KCSImportScriptingSample.zip file. Default path:
C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample
-
Paste this script file to a local path. In Additional settings tab of KC Plug-In Destination configuration, configure Rerouting\Document conversion script path field to browse the SampleDocumentCombineScript.cs file.
-
Restart the KC Plug-in service.