Overview of Settings and Workflows
The low-level CSDK API is not object oriented, but a functional interface. To achieve anything, a function needs to be called, and one usually declares which page is the target of the particular function. In case of functional programming it is widespread practice to state the mode of executing in the arguments of the function:
DoSth (With.This, Like.This1, Like.This2, Like.This3 ...)
However, in low-level CSDK API it would be necessary to provide so many arguments that the argument list of the functions became impossible to handle.
Therefore an argument-set called Setting came to be defined. Settings are thematically organized into a tree structure and they can be reached based on their names where each word delimited by a dot represents a node within the tree. For example, the setting Kernel.Languages stores the preset recognition languages. This setting tree gets initialized when CSDK loads but it can change and extend at runtime. Also, more than one instance of the setting tree can exist and they can be referred to by an identifier called Setting ID. At launch only the setting tree with a 0 identifier initializes, further ones are created on-demand.
We could call CSDK's functional API "intuitive" functional API, since calling one function consists of the following sequence:
- The user sets the Setting they consider important.
- Calls the requested function, where functions usually follow this pattern:
DoSth (With.ThisPage, With.This.SettingID)
The user unknowingly makes implicit provisions even about those settings which were originally not intended to be specified, because the settings already have some initial default values.
Settings in IPRO can be reached via Setting managers. A setting manager object can be requested either from the Engine or Document objects. The Engine's setting manager handles the setting tree with 0 identifier initiated at launch. Each new document receives a private setting tree which is a copy of the Engine setting tree's snapshot. At document loading, the document settings obviously arrive from the file. The essential settings of documents can be reached directly through properties (for example, the IDocument.Rotation sets the setting Kernel.Imf.Rotation). This is a convenient support intended for users so they can access certain settings without knowing the setting names. It can be stated that possessing a setting manager and having a thorough KernelAPI documentation on settings means full control over CSDK.
What is a workflow?
IPRO prefers to execute every activity in a workflow. Workflows consist of steps, the most common (and most general one) is the "Load-Recognize-Export" workflow made up of 3 steps. The workflow steps naturally call the low-level API functions, (the most important difference being the organization). If demanded, more than one instance of the workflow steps can be launched at the same time, while running multi-threaded. For instance, it is a real scenario to have the 2nd page of a multipage image file only loading, while the 1st page already being handled by the Recognize step. Multi-threaded workflow execution can only be effective in case of several pages being processed en gross, while the "Load-Recognize-Export" workflow of a one page image file is linear. The operation of workflow steps is determined by the workflow step parameters. These are named variables and there is a high correlation between settings and workflow step parameters.
Certain parameters entirely correspond to a given setting. For instance, the SP_RCI_LANGUAGES parameter of the Recognize step corresponds to the Kernel.Languages setting. Other parameters do not have a setting equivalent, (like the SP_RCI_AUTOLANGUAGE), these influence the setting independent operation of the step, whether it calls a function or not. Although the parameters and the settings may overlap, the workflow may not modify the document settings, because every step creates a temporary setting tree, which is a copy of the document's settings, and it works on this setting collection.
Basically there are two types of workflows: instant workflow and file workflow. File workflow can be created by the workflow assistant and can be loaded by the LoadWF method of the WFHandler. Instant workflows can be created by the CreateWF, FinalizeWF method pair of the WFHandler. There is a fundamental difference between the operations of the two.
The file workflow always modifies the overlapped settings based on its parameters, because provisions were made on these at the time of workflow creation. The instant workflow does NOT modify settings, because it assumes that the user previously set them. However, the instant workflow can still be fine-tuned with the SetTempParam method of the WFHandler. The creation of an instant workflow usually happens according to the following scenario:
IWFHandler.SetTempParam
...
IWFHandler.SetTempParam
IWFHandler.CreateWF
IWFHandler.FinalizeWF (optional; if not called, then it is called by StartWorkflow )
IWFHandler.StartWorkflow
With the help of SetTempParam calls, the user compiles an optimal parameter set for processing. Modifying more parameters than the workflow deals with is not a problem, since the WFHandler takes into account only the parameters matching to steps of the workflow. The last argument of the SetTempParam is a Boolean (ForceUse). It is recommended to set it to True. The effect of SetTempParam is the following: the setting independent parameters are set irrespective of the value of the ForceUse. The setting dependent parameters are set in case ForceUse=True is set, i.e. the step will set the setting during its execution. In the case of ForceUse=False, the setting will be set only if it is not otherwise determined.
SetTempParam calls must come before the CreateWF call, because depending on their values, a different type of workflow might be created (e.g.: it is decided here whether Proofreading will be involved into a Load-Recognize-Export workflow). The workflow steps and the parameters of the individual steps can be reached after FinalizeWF (see IWFStep.Parameter property), but modifying their values has no influence on the given execution.
The steps of file workflow are available after LoadWF, and its parameters can be modified.
What is a Setting?
IPRO has objects like Converters, Scanners. Of course the properties of these objects are also stored in Settings.
The Setting manager recognizes the properties, but it is highly advised not to modify their values by the Setting manager. There are logical relations between the individual properties known by the individual scanners and converters, but the user may not be familiar with their cross-effects. As a consequence, Scanner and Converter objects should be used to access these settings. The Converters and Scanners collections are provided by the Engine, hence they belong to the Engine setting tree. There is quite a difference between their scopes: the Engine's setting tree will be inherited by every new Document but a Document's setting tree has effect only on the given Document object.
Before the execution of a workflow, WFHandler copies Converters' and Scanners' settings to the Document's setting tree, if the user does not make any provisions (see later), so each Scanner and Converter will behave in the same way in every workflow.
There are two special parameters called SP_EXP_USEENGINECONVERTERS and SP_SCI_USEENGINESCANNERS, whose default setting is True. If the user modifies their values, then copying is skipped. Using the two parameters makes sense only if the user called the CloneAt method of a given Scanner or Converter beforehand. This method takes an ISettingManager as an argument, which can be requested from a document. After executing CloneAt the user has a Scanner or Converter that is attached to the setting tree of the Document, i.e. the user is able to configure them on a per document basis without modifying the converters and scanners of the Engine.