Find Table Cell Occurrence

Finds a specific value occurrence and its position in the data table. Use a specific text or regular expression.

Command availability: IBM RPA SaaS and IBM RPA on premises

Script syntax

IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.

findTableCell --dataTable(DataTable) [--useRegex(Boolean)] --value(String) --regexPattern(String) [--regexOptions(DisplayableRegexOptions)] --search(FindTableRowSearches) --index(Numeric) --direction(FindTableRowDirectionsWrapper) --occurrencetype(FindOccurrenceTypes) --occurrence(Numeric) (Boolean)=success (Numeric)=row (Numeric)=column (String)=columnName (Scalar)=value (Numeric)=count

Input parameter

The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.

Designer mode label Script mode name Required Accepted variable types Description
Data Table dataTable Required Data Table Data table that is evaluated.
Use Regex useRegex Required Boolean Enable to search for contents in the data table by using a regular expression.
Value value Required only when the Use Regex parameter is True Text Text value to find in the data table.
Regular Expression regexPattern Required only when the Use Regex parameter is True Text Enter a regular expression to find matches in the data table.
Options regexOptions Optional DisplayableRegexOptions Select an option to filter the search for matches using the regular expression.

See the regexOptions parameter options.
Regular expression (Obsolete) regex Optional Boolean Enable to use a "Regular Expression" to search for the table cell.

This parameter is obsolete, use the Use Regex parameter instead.
Ignore case (Obsolete) ignorecase Optional Boolean Enable to allow case-insensitive matching.

This parameter is obsolete, use the Options instead.
Dot matches new line (Obsolete) dotmatchesnewline Optional Boolean Enable to allow the dot character (.) to match every character, including "\n".

This parameter is obsolete, use the Options parameter instead.
Ignore white space (Obsolete) freespacing Optional Boolean Enable to eliminate blank spaces and breaks without adding an escape character.

This parameter is obsolete, use the Options parameter instead.
Explicit capture (Obsolete) explicitcapture Optional Boolean Enable to allow capturing only text corresponding to the named group using the format (? ).

This parameter is obsolete, use the Options parameter instead.
Multiline (Obsolete) multiline Optional Boolean Enable to allow ^ and $ to match the beginning and end of any line, respectively, and not just the beginning of an entire string.

This parameter is obsolete, use the Options parameter instead.
Search search Required FindTableRowSearches Select the options that are used to search for the cell contents. See the search parameter options for details.
Column or Line index Only when Search in Rows, Columns Number A tuple to the positional index of the table cell. Example: 5,6
Direction direction Required FindTableRowDirectionsWrapper Select one of the options that are used to control from which direction the search starts. See the direction parameter options.
Occurrence Type ocurrencetype Required FindOccurrenceTypes Determines which instance the cell should be found.

See the ocurrencetype options parameter.
Occurrence occurrence Only when Occurrence Type is N Number Number of occurrences that you want to find.

regexOptions parameter options

The following table displays the options available for the regexOptions input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label Script mode name
Compiled Compiled
Culture Invariant CultureInvariant
ECMA Script ECMAScript
Explicit Capture ExplicitCapture
Ignore Case IgnoreCase
Ignore Pattern Whitespace IgnorePatternWhitespace
Multiline Multiline
Right To Left RightToLeft
Singleline Singleline

direction parameter options

The following table displays the options available for the direction input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label Script mode name
Bottom to top and left to right Bottom2TopLeft2Right
Bottom to top and right to left Bottom2TopRight2Left
Left to right and bottom to top Left2RightBottom2Top
Left to right and top to bottom Left2RightTop2Bottom
Right to left and bottom to top Right2LeftBottom2Top
Right to left and top to bottom Right2LeftTop2Bottom
Top to bottom and left to right Top2BottomLeft2Right
Top to bottom and right to left Top2BottomRight2Left

occurrencetype parameter options

The following table displays the options available for the ocurrencetype input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label Script mode name
First occurrence First
Last occurrence Last
Nth occurrence N

search parameter options

The following table displays the options available for the search input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label Script mode name Description
Rows rows Searches for the occurrence on the defined rows.
Column Column Searches for the occurrence on the defined columns.
All cells Allcells Searches for the occurrence on all the cells.

Output parameter

Designer mode label Script mode name Accepted variable types Description
Success success Boolean Returns True if the cell is successfully found, otherwise returns False.
Row row Number Returns the index of the row where the cell was found.
Column column Number Returns the index of the column where the cell was found.
Column Name columnname Text Returns the cell's column name.
Value value Primitives Returns the contents of the cell that was found.
Count count Number Returns the number of occurrences found.

Example

the following example demonstrates the use of the Find Table Cell Occurrence command to find the value that you want in the data table.

defVar --name excelFile --type Excel
defVar --name obtainedSheet --type DataTable
defVar --name searchSuccess --type Boolean
defVar --name rowNumber --type Numeric
defVar --name columnsNumber --type Numeric
defVar --name columnName --type String
defVar --name cellContent --type String
defVar --name occurrencesQuantity --type Numeric
// Enter the file path to the excel file
excelOpen --file "Excelfile.xlsx" excelFile=value
excelGetTable --file ${excelFile} --getfirstsheet  --entiretable  --hasheaders  obtainedSheet=value
// Enter the parameters values to find a specific value occurrence.
findTableCell --dataTable ${obtainedSheet} --value "Value occurrence" --search "AllCells" --direction "Left2RightTop2Bottom" --occurrencetype "First" searchSuccess=success columnName=columnName rowNumber=row columnsNumber=column occurrencesQuantity=count cellContent=value
logMessage --message "Success: ${searchSuccess}\r\nRow: ${rowNumber}\r\nColumn: ${columnsNumber}\r\nColumn Name: ${columnName}\r\nContent: ${cellContent}\r\nOccurrences: ${occurrencesQuantity}" --type "Info"