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.

  • output: The resultant concatenated PDF file.

  • body: The body of the message.

  • input: The list of attachments to concatenate.

  • options: Options to use for the concatenate operation.

  • appendBodyFirst: If set to True, appends body first and then attachments. If set to False, appends attachments first and then body.

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:

  • PDPageDrawSmoothText = 0x00000001

  • PDPageDrawSmoothLineArt = 0x00000002

  • PDPageDrawSmoothImage = 0x00000004

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:

  • 0: Disabled

  • 1: Letter

  • 2: Legal

  • 3: A3

  • 4: A4

  • 5: A5

  • 6: Match best

  • 7: Match best Euro

  • 8: Match best US

ConversionDetails

imageCoding

Integer

Gets or sets the output color. The possible values are:

  • 1: Black and White

  • 2: Grayscale

  • 3: Color

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:

  • PDF

  • PDFA1a

  • PDFA1b

  • PDFA2a

  • PDFA2b

  • PDFA2u

  • PDFA3a

  • PDFA3b

  • PDFA3u

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:

  • 0: Off

  • 1: On

DocumentConversionOptions

Pdf

Integer

Gets or sets a value to convert to PDF or not.

The possible values are:

  • 0: Off

  • 1: On

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.

This feature is only applicable for PDF conversion.

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:

  1. Copy the script file AppendBodyToAttachments_FR7043.cs from the KCSImportScriptingSample.zip file. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample

  2. 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.

  3. Ensure that the Convert to option is set to PDF in the Import settings tab.

  4. 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:

  1. Copy the script file SampleUnzipScript.cs from the KCSImportScriptingSample.zip file. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample

  2. 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.

  3. 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:

  1. Copy the script file SampleDocumentConverterScript.cs from the KCSImportScriptingSample.zip file. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample

  2. 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.

  3. Ensure that the Import original content option is selected in the Import settings tab.

  4. 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.

This feature is only applicable for PDF conversion.

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:

  1. Copy the script file SampleDocumentCombineScript.cs from the KCSImportScriptingSample.zip file. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\KCPlugIn\ScriptSample

  2. 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.

  3. Restart the KC Plug-in service.