Skip to main content

xSuite Interface Windows Prism 5.x – Online Help

General Properties

The following properties are used for the general definition of the processing scenario.

Property

Description

Constant[]

Definitions of constants (see Constants)

General.ScenarioName

Freely selectable name of the scenario

This name is an addition to the technical name and is displayed in the logging. If this property value is missing, the name of the scenario configuration file will be used instead.

General.ScenarioDescription

Free description text for the scenario

This description text is used primarily for the purposes of display in the configuration program.

General.Priority

Numeric value for setting priorities, starting with 1 (highest) and going to to n (lowest)

With this priorization, those documents of the scenario are processed which were selected by a worker instance from the administrative database.

This property only applies if a worker instance processes data of different scenarios one after the other. Within a priority level, the processing takes place in the order of the time at which documents are read in.

Default value: 5

General.RetryMax

General.RetryDelayMacro(*)

Properties for controlling automatic retries of processing a document in case of an error

This only affects documents that have been successfully read into the database (i.e., documents in the processing and output steps). Documents that are already unreadable in the input step can only be reprocessed after manual intervention.

This functionality can be used if, for example, temporary connection problems to an output system are to be expected. If there are content errors in the document data that cannot be fix automatically even by repeated processing attempts, it should not be used.

The numeric property .RetryMax specifies the maximum number of retries before a document is set to error status (default value: 0, i.e. no retries).

If the function is to be active, configure .RetryDelayMacro as well. This configuration is performed dynamically via a field macro expression, which which could well consist of just a single constant value. This macro must return a numerical value specifying the duration of the waiting time in minutes until the next processing attempt is to be initiated.

This macro is also used to determine whether a new processing attempt is to be made at all. If the macro returns the value 0, no more attempts will be made. In addition, the following system variables are available in this context so that it can be decided dynamically during macro execution. This means that automatic repetition can be restricted to certain types of errors, for example.

  • ErrorText: message text as it would be written to the log for the error in question

  • EventId: event ID for classifying the error context (see Event Classes)

  • RetryNo: number of the pending retry (with counting starting at 1)

General.BatchLogFile

Path of a batch-specific log file (optional)

This log file bundles all information on the processing sequence of a single batch. In terms of content, these are the same entries as those in line with the global configuration in Logging.File. Here, however, these are only entries that relate to the respective batch.

Batch-specific logging only starts once a batch has been successfully read in and initially transferred to the administrative database. Entries relating to the previous read-in process must therefore be taken from the global log of the responsible input worker.

To create the file path of the log file dynamically, such that files are separated by batch, the following variables can be used for integration into the path:

Notice

As with global logging, the variables %Date% and %Tenant% can also be used.

  • %FileName%: name of the input file

  • %FileBaseName%: base name of the input file (without file extension)

  • %FilePath%: full path of the input file (i.e., directory and file name)

  • %FileBasePath%: full base path of the input file (without file extension)

  • %BatchName%: name of the batch

  • %BatchId%: database key of the batch

  • %BatchExtId%: external ID of the batch

  • %BatchUuid%: UUID of the batch

The variables %File***% refer to the input file that was read by the input system. These variables are only available if the input system is a system that reads directly from the file system. For custom input systems of type "Custom," there is currently no provision for reporting the path of the batch-related input file back to the program. These variables can therefore not be used for input systems of the type "Custom."

The variables %Batch***% refer to properties of the newly created batch, and correspond to the document variables of the same name (see Variables).

In xSuite Interface Version 4.x, a log file was automatically created directly in the input directory and under the name of the input file for file-based input systems. To emulate this behavior in the present version of xSuite Interface, %FilePath%.log can be configured as the path. For input systems that are not file-based, however, a fixed log folder and variables should be used that establish the reference to the batch (e.g., c:\log\[%BatchId%] %BatchName%.log).

If multiple worker instances are configured to work in parallel on several documents in the same batch, the readability of the batch log will be restricted. These parallel processing instances are written in unsorted sequence to the same log file. In such a case, it may be helpful to use the global logs, as these allow separation into separate files per instance.

General.FileMacroOptions.PdfALevel

General.FileMacroOptions.JpegQuality

General.FileMacroOptions.PngCompression

General.FileMacroOptions.FormFeed(#)

General.FileMacroOptions.ImageResolution

General.FileMacroOptions.ImageBitDepth

General.FileMacroOptions.PageMargin

General.FileMacroOptions.FitWorksheetToPage

General.FileMacroOptions.DefaultFont

General.FileMacroOptions.FontsFolder

General.FileMacroOptions.ExtractFilesPdfLib

Default settings for the execution of certain file macros which apply globally within the scenario

Depending on the graphics library used and the specific conversion function, some settings might not be supported. If a setting is not supported, a different value will implicitly be used or an error triggered (e.g., for an unsupported PDF/A version).

  • .PdfALevel: version of the PDF/A standard when outputting PDF files in PDF/A format:

    • PDF_A_1a (PDF/A-1a)

    • PDF_A_1b (PDF/A-1b)

    • PDF_A_2a (PDF/A-2a) (default value)

    • PDF_A_2b (PDF/A-2b)

    • and others up to PDF_A_4f (PDF/A-4f)

  • .JpegQuality: numeric output quality of JPEG files from 1 (worst) to 100 (best) (default value: 75)

  • .PngCompression: numeric degree of compression for PNG files to be output from 0 (none) to 10 (maximum) (default: 6)

  • .FormFeed: Form feed character when outputting multi-page text files (default value: \f, i.e., character code 12)

  • .ImageResolution: numeric resolution for raster image files to be output in DPI (default value: 300)

  • .ImageBitDepth: numeric color depth for raster image files to be output with valid values 1, 8 and 24 (default value)

  • .PageMargin: numeric width of the page margin in millimeters; set explicitly when converting Microsoft Office documents, and set output paper size to DIN A4 (default value: -1, i.e., no change to the original setting)

  • .FitWorksheetToPage: Boolean value determining whether the contents of a worksheet will be displayed on a single output page when converting Microsoft Excel files (default: true); this will override the paper size specified under .PageMargin

  • .DefaultFont: name of the default replacement font for a Microsoft Word document if the original fonts are not installed (only relevant when using xSuite Interface in Linux)

  • .FontsFolder: directory path for fonts to be used in a Microsoft Word document if they are not installed in the default folder of the operating system (only relevant when using xSuite Interface in Linux)

  • ExtractFilesPdfLib: Selection of the graphics library for extracting file attachments from a PDF file, as follows:

    • Aspose

    • GdPicture (default value)

Lookup[].Name

Lookup[].Item[]

Definition from lookup lists

Lookup lists can be accessed via macro functions like Lookup() and LookupLike().

If multiple lists exist, use the .Name property to make them uniquely identifyable. The elements of lists such as these consist of key/value pairs. Specify these pairs in the following two subparameters:

  • Key*: key

  • Value: value

General.Database[].Name

General.Database[].ConnectionString(§%)

General.Database[].Password(§)

General.Database[].Command(%)

Connection parameter(s) to be configured separately and command for accessing an external database in a macro function (e.g., QueryDbField())

These parameters have individual configuration properties to limit the length of the parameter list of the respective functions. In the functions, these parameters are referenced via the .Name property.

The .ConnectionString is the connection string to the database. The supported systems are described at External Data Sources.

The password required in the connection string can be defined separately in .Password. The variable %Password% can then be used to include the password in the string.

The database command to be executed in .Command depends on the context of the macro function. In most use cases, the command contains a SELECT statement.

General.WebService[].Name*

General.WebService[].Url*(%)

General.WebService[].Method

General.WebService[].ProxyServer

General.WebService[].AuthMode

General.WebService[].User

General.WebService[].Password(§)

General.WebService[].CertificateName

Connection parameter(s) to be configured separately to an external web service for use in a macro function (e.g., CallWebService())

These parameters have individual configuration properties to limit the length of the parameter list of the respective functions. In the functions, these parameters are referenced via the .Name property. Such functions enable the generic call of simple web services, but are not a fully-fledged replacement for the project-specific implementation of special web service interfaces. These functions do not support the processing of multipart data, neither in the request nor in the response.

Enter the full URL of the web service to be called in .Url, and include any necessary path and parameter. Specify the HTTP method in . Method (default value: POST).

If communication is to run via a proxy server, this can be defined in .ProxyServer (for syntax, see Proxy Server Connection). If the web service requires authentication, the following modes are available via the . AuthMode:

  • None: no authentication (default value)

  • Basic: basic authentication with user name and password

  • ApiKey: API key

  • Certificate: client certificate

Enter the properties for authentication in Basic mode in .User and .Password. In ApiKey mode, use these properties to specify the key name (as .User, e.g., "Bearer" and the key value (as .Password). Specify the certificate in Certificate mode in .CertificateName using the name of the certificate. The name must correspond to the .Name property of a certificate of the type Certificate[].Usage: "Client", which is defined globally under Certificate[].

In this section: