Migrating from the Recognition Server 4 Web Services API to the FineReader Server 14 Web Services API

This guide is based on a sample C# project that accesses a Web service via a Web reference.

In most scenarios, the FineReader Server 14 Web Services API  is backward-compatible with the Recognition Server 4 Web Services API. To migrate to the latest version, only the following actions are required:

  1. Delete the Web reference for the Recognition Server 4 Web Services API  from your project.
  2. Add a Web reference for the FineReader Server 14 Web Services API to your project (see this this MSDN section for details).
  3. In the Web reference name field of the Add Web Reference dialog box, you can specify a name that is different from the old name of the Web reference. In his case you will need to change the namespaces used in your project accordingly.
  4. Recompile your project.
  5. If the compilation results in an error, please refer to the second part of this document, where the possible backward-compatibility issues are described.

Changes in the FineReader Server 14 Web Services API  that break backward compatibility

All examples use the following aliases for the namespace:

using RS4 = SampleProject.RS4SoapService; // Web reference for RS4 Web Services API
using FRS14 = SampleProject.FineReaderServer14; // Web reference for FRS14 Web Services API

  1. The FormatSettings property has been deleted from the OutputDocument class.

Previously, a copy of export settings that were used to obtain the output document was stored as a property of this document. This is redundant, as export settings are also stored in the XmlResult.ExportParams.Formats collection.

Now, the OutputDocument class has two new properties available instead of the FormatSettings property:

  • FileFormat, a property of the FRS14.OutputFileFormatEnum type that determines the export format (previously, FormatSettings.FileFormat was used for this purpose)
  • FileFormatId, a property of type String which specifies the unique ID of the format and includes string representation of the GUID.

An example of the FileFormatId string:

"{C8DFF56C-8463-4595-A175-35B7E3191CE7}"

The FileFormatId  property of type String has been added to the OutputFormatSettings class. It identifies the export format. You can find the required OutputFormatSettings object in the FRS14.XmlResult.ExportParams.Formats collection by comparing the OutputFormatSettings.FileFormatId properties.

Important! Comparison of FileFormatId values must be case-insensitive.

// Before:
var formatSettings = outputDoc.FormatSettings;

// Now:
if (outputDoc.FileFormat != FRS14.OutputFileFormatEnum.OFF_NoConversion)
{
   var formatSettings = FindFormatById(xmlResult.ExportParams.Formats,
       outputDoc.FileFormatId);
}
else
{
// In this case, ExportParams.Formats might not contain the relevant format.
}

// Additional functions:
bool AreFormatIdsEqual(string first, string second)
{
   return first.Equals(second, StringComparison.InvariantCultureIgnoreCase);
}

FRS14.OutputFormatSettings FindFormatById(FRS14.OutputFormatSettings[] formats,
string id)
{
   return formats.Where(f => AreFormatIdsEqual(f.FileFormatId, id))
.FirstOrDefault();
}

  1. The SkipRecognizePdfsWithTextLayer* properties have been deleted from PDFExportSettings and PDFAExportSettings classes.

// Before:
pdfSettings.SkipRecognizePdfsWithTextLayer = true;
pdfSettings.SkipRecognizePdfsWithTextLayerCoefficient = 50;

// Now: Use the PdfMode option of the XmlTicket.PreprocessingParams object
// Possible values:
//     PM_Text – Always use text in PDF file
//     PM_Auto – Auto
//     PM_Ocr – Always use OCR
xmlTicket.PreprocessingParams.PdfMode = FRS14.PdfModeEnum.PM_Auto;

  1. The PES_MaxSpeed scenario has been deleted from the PDF settings.

// Before:
      pdfSettings.Scenario = RS4.PdfExportScenarioEnum.PES_MaxSpeed;

// Now: use PES_Balanced
   pdfSettings.Scenario = FRS14.PdfExportScenarioEnum.PES_Balanced;

  1. In the RecognitionParams class, the type of the  TextProperties property has been changed from Integer to TextTypeEnum.

// Before:
      ticket.RecognitionParams.TextTypes = 1; // Was used for type Normal
      ticket.RecognitionParams.TextTypes = 3; // Was used for types Normal and Typewriter

// Now
   ticket.RecognitionParams.TextTypes = FRS14.TextTypeEnum.TT_Normal;
   ticket.RecognitionParams.TextTypes = FRS14.TextTypeEnum.TT_Normal | FRS14.TextTypeEnum.TT_Typewriter;

  1. The properties that include collections of errors and warnings have changed in the XmlResult, InputFile, and JobDocument classes.

Previously, errors and warnings in all these classes were stored as collections of strings in Errors and Warnings properties. Now, each class stores messages as a collection of objects of the JobMessage type in one property — Messages. Besides, there is new type of messages named Information.

The JobMessage class contains the following properties:

  • The Type property of type JobMessageType is the type of the message
  • The Code property of type int is the numeric code of the message
  • The UnicodeStr property of type String is the text of the message

Definition of the JobMessageType enumeration:

public enum JobMessageType {
   JMT_Error,
   JMT_Warning,
   JMT_Information,
}

An example where all the XmlResult messages are sent to the console:

// Before:
foreach (string str in xmlResult.Warnings)
{
   Console.WriteLine("Type = Warning, Text = {0}", str);
}
foreach (string str in xmlResult.Errors)
{
   Console.WriteLine("Type = Error, Text = {0}", str);
}

// Now:
foreach (var msg in xmlResult.Messages)
{
   Console.WriteLine("Type = {0}, Code = {1}, Text = {2}",
msg.Type, msg.Code, msg.UnicodeStr);
}

  1. The settings of headers and footers have been modified in the PDFExportSettings and PDFAExportSettings classes.

Previously, headers and footers were set using the PDF(A)ExportSettings.HeaderAndFooter property. Users were able to set up to 6 headers and footers for a page. The font, margins, and Bates numbering parameters were the same for all headers and footers. In the example below, the header is positioned in the left-hand side of the page (previous version of the API):

// Text and positioning
pdfSettings.HeaderAndFooter.LeftHeader = "Text in top left corner";
// Font parameters
pdfSettings.HeaderAndFooter.FontName = "Arial";
pdfSettings.HeaderAndFooter.FontSize = 14;
pdfSettings.HeaderAndFooter.IsBold  = true;
pdfSettings.HeaderAndFooter.IsItalic = false;
pdfSettings.HeaderAndFooter.IsUnderlined = true;
pdfSettings.HeaderAndFooter.TextColor = 0;
// Margins
pdfSettings.HeaderAndFooter.IsInInches = true;
pdfSettings.HeaderAndFooter.TopMargin = 1;
pdfSettings.HeaderAndFooter.BottomMargin = 1;
pdfSettings.HeaderAndFooter.LeftMargin = 1.5;
pdfSettings.HeaderAndFooter.RightMargin = 1.5;
// Bates Numbering parameters
pdfSettings.HeaderAndFooter.StartingNumber = 1;
pdfSettings.HeaderAndFooter.NumberOfDigits = 5;

Now headers and footers are set using the PDF(A)ExportSettings.PageStamps property. Users are able to set an unlimited number of headers and footers in the PageStamps.Items collection. Font and margin parameters are now set separately for each header or footer. The Bates numbering parameters will still apply to all headers and footers. In the example below, the header is positioned in the left-hand side of the page (current version of the API):

var pageStamp = new FRS14.TextPageStampSettings();
// Text
pageStamp.Text = "Text in top left corner";
// Positioning
pageStamp.Position = new FRS14.PageStampPositionSettings();
pageStamp.Position.VerticalAlignment = FRS14.PageStampVerticalAlignment.Top;
pageStamp.Position.HorizontalAlignment = FRS14.PageStampHorizontalAlignment.Left;
// Margins
pageStamp.Margins = new FRS14.PageStampMarginSettings();
pageStamp.Margins.Units = FRS14.PageStampMarginUnits.Inches;
pageStamp.Margins.TopMargin = 1;
pageStamp.Margins.BottomMargin = 1;
pageStamp.Margins.LeftMargin = 1.5;
pageStamp.Margins.RightMargin = 1.5;
// Font parameters
pageStamp.TextStyle = new FRS14.PageStampTextStyleSettings();
pageStamp.TextStyle.FontName = "Arial";
pageStamp.TextStyle.FontSize = 14;
pageStamp.TextStyle.IsBold = true;
pageStamp.TextStyle.IsItalic = false;
pageStamp.TextStyle.IsUnderlined = true;
pageStamp.TextStyle.TextColor = new FRS14.ColorSettings
{ Red = 0, Green = 0, Blue = 0 };
// Bates numbering parameters that are common to all headers and footers
pdfSettings.PageStamps.BatesCounter.StartingNumber = 1;
pdfSettings.PageStamps.BatesCounter.NumberOfDigits = 5;
// A collection that contains one element (multiple elements can be added)
pdfSettings.PageStamps.Items = new FRS14.PageStampSettingsBase[] { pageStamp };

3/26/2024 1:49:49 PM

Please leave your feedback about this article

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.