Objects - ABBYY Documentation

The following functions are available for creating custom scripts. To access object instances, use the commandArgs variable. All variables in this section are global and visible across the entire program.

Field paths

Some functions take the path to a field as an input parameter. The path comprises the field name and the names of its parent elements (field group, section). For tables, repeating tables, and repeating groups, specify the instance number starting at 0 (zero). For example, ['Document Section 1', 'Group[10]', 'Field3'], where [10] is the number of the instance of the repeating group.

Functions for working with fields

getCurrentField

getCurrentField() Returns a link to the field object that uses the current custom script.

getFieldByName

getFieldByName(namesPath) Returns a link to the field for which the custom script has been opened.

Parameter	Description
`namesPath`	An array of field and group names that form the path to the field, or a link to a field object. See Field paths.

getFieldValue

getFieldValue(namesPath) Returns the field value: a string for a TextField field, a checkmark value for a Checkmark field, or a string array for a Checkmark Group field.

Parameter	Description
`namesPath`	An array of field and group names that form the path to the field, or a link to a field object. See Field paths.

setCurrentFieldValue

setCurrentFieldValue(value, forced, onSaved) Modifies the value of the field for which the custom script has been opened.

Parameter	Description
`value`	The field value.
`forced`	Optional. Updates the field value and records new data. When `false`, the field value in the Document Definition is updated only after `save()` is called. When `true`, the field value is updated immediately. For a custom script, an update occurs regardless of the mode. Default is `false`.
`onSaved`	Optional. A callback function. Called when `forced` is set to `true`.

setFieldValue

setFieldValue(namesPath | field, value, forced, onSaved) Modifies the field value.

Parameter	Description
`namesPath`	An array of field and group names that form the path to the field, or a link to the field object. See Field paths.
`value`	The value of the corresponding field.
`forced`	Optional. Updates the field value and records new data. When `false`, the field value in the Document Definition is updated only after `save()` is called. When `true`, the field value is updated immediately. For a custom script, an update occurs regardless of the mode. Default is `false`.
`onSaved`	Optional. A callback function. Called when `forced` is set to `true`.

save

save() Closes the window where the custom script is executed and saves the changes.

cancel

cancel() Closes the window where the custom script is executed without saving the changes.

Functions for working with data sets

addEntity

addEntity(entityInfo: {cacheName, columns, values}, onResult(newId)) Adds an entry to the data set.

Parameter	Description
`entityInfo.cacheName`	A name for the data set.
`entityInfo.columns`	Names for the columns where data will be recorded. Array of strings.
`entityInfo.values`	The values for the corresponding columns. Array of strings.
`onResult`	A callback function that receives the ID of the record created in the data set.

editEntity

editEntity(entityInfo: {cacheName, columns, values}, onResult()) Edits an entry in the database.

Parameter	Description
`entityInfo.cacheName`	A name for the data set.
`entityInfo.columns`	Names for the columns where data will be recorded. Array of strings.
`entityInfo.values`	The values for the corresponding columns. Array of strings.
`onResult`	A callback function.

getDict

getDict({cacheName, filters: [{FieldName, FieldValue}], cursorPos, allowMultipleColumnResults}, onResult(param: {FieldName, FieldValue, BoldMask}[][]))

Searches the data set for a specified value or part of it.

Parameter	Description
`cacheName`	The data set name.
`filters`	Search parameters. Each entry has `FieldName` (the field name; leave empty to search all fields) and `FieldValue` (the field value).
`cursorPos`	The position of the cursor in the entry field. If a value is entered partially and the cursor is after the typed symbols, they are treated as a prefix for the searched value. If the cursor is before a partially typed word, those symbols are treated as its ending. For example, when searching for a company name, typing `ADO` with the cursor after it selects `AVOCADO`; typing `ADO` with the cursor before it selects `ADONIS`.
`allowMultipleColumnResults`	Returns the values of the fields that were found. A data set may contain entries where one field name (`FieldName`) corresponds to multiple field values (`FieldValue`), for example several variations of a company name in the `CompanyName` column. `true` returns and records all field values that satisfy the search conditions; `false` returns and records a single result that best fits.
`onResult`	A callback function that returns a search result array. Each result is a string from the data set (itself a string array), where each string holds the field name, its value, and the `BoldMask` parameter.

BoldMask is a string of 0 and 1 the same length as the value found. 1 marks a symbol from the found value that matches the corresponding symbol in the search field, and 0 marks one that does not. For example, if a data set contains CompanyName: ABBYY and a search is carried out for the symbols ABB, the following is returned:

[
  [
    {
      FieldName: 'CompanyName',
      FieldValue: 'ABBYY',
      BoldMask: '11100'
    },
  ]
]

The returned array can contain several values, including some that did not initially fit the search conditions. Results are sorted by BoldMask value in descending order, starting with the strings that best match the search conditions.

getDictAll

getDictAll({cacheName, filters: {FieldName, FieldValue}}, }, onResult(param: {FieldName, FieldValue, BoldMask}[][])) Searches the database for the entire value specified. Returns the values of all fields that were found.

Parameter	Description
`cacheName`	The data set name.
`filters`	An object array. Each entry has `FieldName` (the field name; leave blank to search all fields) and `FieldValue` (the field value).
`onResult`	A callback function that returns a search result array. Each result is a string from the data set (itself a string array), where each string holds the field name, its value, and the `BoldMask` parameter.

[
  [
    {
      FieldName: 'CompanyName',
      FieldValue: 'ABBYY',
      BoldMask: '11100'
    },
  ]
]

Functions for working with the document form

selectRow

selectRow(tablePath, rowNumber) Marks a table row as selected.

Parameter	Description
`tablePath`	An array of field and group names that form the path to the table field, or a link to a table object. See Field paths.
`rowNumber`	The number of the row to select, zero-based.

deselectRow

deselectRow(tablePath, rowNumber?) Removes the selection from a table row.

Parameter	Description
`tablePath`	An array of field and group names that form the path to the table field, or a link to a table object. See Field paths.
`rowNumber`	The number of the row to deselect, zero-based. If omitted, the selection is removed from all rows in the table.

scrollFormToField

scrollFormToField(namesPath) Scrolls the form editor to bring the field into view.

Parameter	Description
`namesPath`	An array of field and group names that form the path to the field, or a link to a table object. See Field paths.

getDomElementPosition

getDomElementPosition(domId, onResult: (result?: {width, height, top, left, right, bottom})) Gets the position of an element in the form editor window and returns the result of a callback function.

Parameter	Description
`domId`	Element ID in DOM format.
`onResult`	A callback function that receives the object with the DOM coordinates of the element (`width`, `height`, `top`, `left`, `right`, `bottom`) relative to the top left corner of the browser window.

setStyles

setStyles(styles, callback) Adds CSS styles to the custom action frame window.

Parameter	Description
`styles`	An object with CSS property names and values (see the following example).
`callback`	A callback function.

{
  display: 'block',
  position: 'absolute',
  top: '0px',
  bottom: '0px',
  left: '0px',
  right: '0px',
  width: '100%',
  height: '100%',
  border: '0',
  overflow: 'hidden',
  'overflow-x': 'hidden',
  'overflow-y': 'hidden',
  'z-index': '10000'
}

commandArgs object

Variables

Variable	Type	Description
`commandArgs.params.document`	Document	Stores an object copy of an open document. Use it to access any error, field, or region for the current document.
`commandArgs.params.currentField`	`(Picture \| Checkmark \| Checkmark Groups \| FieldsGroup \| Table \| TextField)`	Returns a link to a field object that reflects the state of the field when the script is called. Part of the document above. If the field value is modified after the script is initialized, the changes are not applied.
`commandArgs.params.appPath`	String	The server’s domain name.
`commandArgs.params.coordinates`	`Object [{X1,X2,Y1,Y2}]`	The coordinates of the DOM element that called the custom script.
`commandArgs.params.currentElementDomId`	String	The ID of the DOM element that called the custom script.

Events

Function	Description
`commandArgs.events.addEventHandler`	Adds an event handler in the global context of the custom script.
`commandArgs.events.triggerHandlers`	Triggers an event in the global context of the custom script.
`commandArgs.events.removeEventHandler`	Deletes an event handler in the global context of the custom script.

Field object types

Custom scripts can access the following field object types and the document object. Every field object exposes the Region object through its Regions property.

Field Group field

Property	Type	Access	Description
`Fields`	`(Picture \| Checkmark \| Checkmark Groups \| FieldsGroup \| Table \| TextField)[]`	Read-only	Array of fields.
`HasTableLayout`	Boolean	Read-only	Specifies whether the field region is a table.
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `4` (field group).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether editing of fields is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name for the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.

Section field

Property	Type	Access	Description
`Fields`	`(Picture \| Checkmark \| Checkmark Groups \| FieldsGroup \| Table \| TextField)[]`	Read-only	Array of fields.
`Pageids`	`Number[]`	Read-only	Identifiers of the pages on which the section is located.
`IsFlexible`	Boolean	Read-only	Specifies whether the section is flexible.
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `6` (section).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.

Table field

Property	Type	Access	Description
`Rows`	`Row[]`	Read-only	List of table rows. See Row object.
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `7` (table).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Specifies whether the field is visible on the data form `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.

Row object

Property	Type	Description
`Id`	number	Row ID.
`RowNumber`	number	The sequence number of the row, counting from zero.
`HasColorImage`	boolean	Specifies whether the row image is in color.
`TableBlockID`	`number[]`	Identifiers of sections, tables, and table blocks forming the path to the table block.
`Cells`	`(Picture \| Checkmark \| CheckmarkGroup \| TextField)[]`	Fields in the table cells.

Text entry field

Property	Type	Access	Description
`Flags`	`Number[]`	Read/write	Array of the same length as the field `Value`, consisting of `0` and `1`. A character in `Value` at the same position as a `0` in `Flags` requires verification.
`Suggests`	`String[]`	Read-only	List of suggested field values.
`Value`	String	Read/write	Field value.
`TextType`	Number	Read-only	Type of text field. See TextType values.
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `0` (text field).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.
`IsVerified`	Boolean	Read/write	Specifies whether the field has been verified.
`NeedVerification`	Boolean	Read-only	Specifies whether the field requires verification.
`NeedDoubleVerification`	Boolean	Read-only	Specifies whether the field requires double verification.
`IsSummary`	Boolean	Read-only	Specifies whether the field is used in the data summary on the data form.

TextType values

Value	Meaning
`0`	Text field
`1`	Numeric field
`2`	Currency amount field
`3`	DateTime field
`4`	Date field
`5`	Time field
`6`	Code field

Checkmark field

Property	Type	Access	Description
`Value`	Boolean	Read/write	Field value.
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `2` (checkmark).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.
`IsVerified`	Boolean	Read/write	Specifies whether the field has been verified.
`NeedVerification`	Boolean	Read-only	Specifies whether the field requires verification.
`NeedDoubleVerification`	Boolean	Read-only	Specifies whether the field requires double verification.
`IsSummary`	Boolean	Read-only	Specifies whether the field is used in the data summary on the data form.

Checkmark Group field

Property	Type	Access	Description
`MaxSelectedCount`	Number	Read-only	Maximum number of selected field values.
`MinSelectedCount`	Number	Read-only	Minimum number of selected field values.
`Values`	`Number[]`	Read/write	Field value. An array of record IDs that make up the list of possible field values (`Variants`).
`Variants`	`{Id: number, Name: string}[]`	Read-only	List of possible field values. Each variant has `Id` (record ID) and `Name` (record name).
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `3` (checkmark group).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`NeedRecognize`	Boolean	Read/write	Specifies whether to retrieve the field value from the region when the rules are checked again.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.
`IsVerified`	Boolean	Read/write	Specifies whether the field has been verified.
`NeedVerification`	Boolean	Read-only	Specifies whether the field requires verification.
`NeedDoubleVerification`	Boolean	Read-only	Specifies whether the field requires double verification.
`IsSummary`	Boolean	Read-only	Specifies whether the field is used in the data summary on the data form.

Picture field

Property	Type	Access	Description
`Caption`	String	Read-only	Custom field name, caption.
`FieldType`	Number	Read-only	Field type. Value: `1` (picture).
`Id`	Number	Read-only	Field ID.
`IsReadOnly`	Boolean	Read-only	Specifies whether field editing is disallowed.
`IsVisible`	Boolean	Read-only	Specifies whether the field is visible on the data form.
`MaxRegions`	Number	Read-only	Maximum number of field regions. If the value is `-1`, any number of regions is allowed.
`Name`	String	Read-only	Service name of the field.
`NamePath`	`String[]`	Read-only	Array of field and group names that form the path to the field.
`Regions`	`Region[]`	Read-only	The field’s regions. See Region object.

Repeating Group of Sections field

Property	Type	Access	Description
`Id`	Number	Read-only	Field ID.
`Name`	String	Read-only	Field name.
`Sections`	`Section[]`	Read-only	Array of fields of the Section field type.
`FieldType`	Number	Read-only	Field type. Value: `8` (recurring section group).

Region object

The Regions property of every field object returns an array of regions with the following structure.

Property	Type	Description
`Id`	number	Region ID.
`Status`	number	Status of the region: `0` region not superimposed (or region is deleted), `1` region is not recognized, `2` the value from the region is substituted in the field.
`PageId`	Number	ID of the page on which the region is located.
`IsNew`	Boolean	Flag to indicate new regions.
`Coordinates`	`Object [{X1,X2,Y1,Y2}]`	Coordinates of the region in the image.

Document object

The document object is available through commandArgs.params.document.

Property	Type	Access	Description
`AssemblingErrors`	`AssemblingError[]`	Read-only	Build errors in the document. See Assembly error object.
`BatchId`	Number	Read-only	The package ID.
`Errors`	`Error[]`	Read-only	Errors in the document. See Error object.
`Fields`	`(Section \| SectionsGroup)[]`	Read-only	List of sections and duplicate sections.
`Id`	Number	Read-only	Document identifier.
`Index`	Number	Read-only	Index of the document in the package.
`Pages`	`Page[]`	Read-only	List of document pages. See Page object.
`ProjectId`	Number	Read-only	Project identifier.
`TaskId`	Number	Read-only	Task ID.
`TemplateId`	Number	Read-only	Definition ID of the document.
`TemplateName`	String	Read-only	The name of the document Definition.
`TemplateVersion`	Number	Read-only	Definition version of the document.
`Version`	Number	Read-only	Document version.

Assembly error object

Property	Type	Description
`DocumentNodeRef`	`number[][]`	List of links, as an array of field IDs, to fields in the form.
`Description`	string	Error description.
`SectionName`	`string[]`	List of sections involved in the error.

Error object

Property	Type	Description
`DocumentNodeRef`	`number[][]`	List of links, as an array of field IDs, to fields in the form.
`Severity`	number	`1` Error, `0` Warning.
`Message`	string	Error text.
`RuleName`	string	The name of the rule that caused the error.

Page object

Property	Type	Description
`Id`	number	Page ID.
`Modification`	number	The revision number of the page.
`HasColorImage`	boolean	Specifies the color of the page.
`ImageResolution`	number	Image resolution.
`KeyValue`	string	The value of the key field page.
`SectionTemplateId`	number	ID section of the page.
`SectionTemplateName`	string	Page section name.
`FlexibleInstanceId`	number	ID of the flexible instance.
`SectionTemplatePageNumber`	number	The page number in the section.
`Comment`	string	Review of the page.
`ImageWidth`	number	Width of the page image.
`ImageHeight`	number	Height of the page image.

​Field paths

​Functions for working with fields

​getCurrentField

​getFieldByName

​getFieldValue

​setCurrentFieldValue

​setFieldValue

​save

​cancel

​Functions for working with data sets

​addEntity

​editEntity

​getDict

​getDictAll

​Functions for working with the document form

​selectRow

​deselectRow

​scrollFormToField

​getDomElementPosition

​setStyles

​commandArgs object

​Variables

​Events

​Field object types

​Field Group field

​Section field

​Table field

​Row object

​Text entry field

​TextType values

​Checkmark field

​Checkmark Group field

​Picture field

​Repeating Group of Sections field

​Region object

​Document object

​Assembly error object

​Error object

​Page object