Match function

Matching returns the number of successfully matched lines. Matched line item results are written to the Order Number (global column ID: 9) and MatchPositionIndex (global column ID: 10000) columns to show the data that is found in the purchase order database. If matching fails, the value in the MatchPositionIndex column displays -1. You can configure the Match function to overwrite existing results. It can be used in Validation for updating the matching information, when a table is manually modified.

When you have configured columns in the used locator to be filled by data from the purchase order database, these columns are filled with content if the corresponding line can be matched. The index information of the line is used to get the additional information from the database.

Public Function Match (_
    ByVal pXDoc As CASCADELib.CscXDocument, _
    ByVal sTableFieldName As String, _
    ByVal sPONumbers() As String, _
    ByVal sVendorID As String, _
    ByVal bOverwriteAll _
    ) As Long

pXDoc: XDocument object that contains the table line items to match.
sTableFieldName: Name of the table field that contains the line items to match.
sPONumbers(): Purchase order numbers used for matching the line items. The formatter setting for the purchase order number is applied to all items in the string array before applying matching.
sVendorID: Vendor ID used for matching the line items, this value is not mandatory and can be filled with an empty string.
bOverwriteAll: Flag that determines if a complete re-match is done. If set to TRUE all existing results for the MatchPositionIndex and the Order Number column are cleared before the match is executed and both table columns are updated with the new values. If set to FALSE only cells that are empty or contain -1 are filled with the matching results.
Return: Long: Returns the number of line items where the MatchPositionIndex is not empty and not -1, what corresponds to the number of overall matched lines independent from the number of updated line items.

When the row is matched, all cells of the row are valid, with the following exceptions:

If the unit price is missing or scaled, the column Unit Price is invalid.
If the total price is scaled, the column Total Price is invalid.
If only the total price is found, only the Total Price is set to valid; the other cells of the row are invalid.
If there are OCR errors or matching fails, the row is invalid.

Note Only rows are matched that do not have a value in the PO Item Number column (empty or -1). If you want to ensure that the matching is updated for all lines you need to clear all values from that column before calling the Match function by setting bOverWriteAll to TRUE.

You can use the following code snippet in your script code to call the Match function.

' Add a reference to "Kofax Cascade Line Item Matching Locator" library to your script!

Private Function Match(pXDoc As CASCADELib.CscXDocument, sClassName As String, sLocatorName As String, sTableFieldName As String, sPONumbers() As String, sVendorID As String) As Long
   Dim pClass As CASCADELib.CscClass
   Dim pLocatorDef As CASCADELib.CscLocatorDef

   ' get the locator definition to use for the matching
   Set pClass = Project.ClassByName(sClassName)
   Set pLocatorDef = pClass.Locators.ItemByName(sLocatorName)

   ' convert it to the LineItemMatchingLocator interface to call the match method
   Dim oIExtMethod As CASCADELib.ICscExtractionMethod
   Set oIExtMethod = pLocatorDef.LocatorMethod
   Dim oILIMLoc As CscLineItemMatchingLocLib.CscLineItemMatchingLocator
   Set oILIMLoc = oIExtMethod

   Match = oILIMLoc.Match(pXDoc, sTableFieldName, sPONumbers, sVendorID, False)
   ' if 0 is returned nothing are matched, table is not changed.

End Function

Using the Match function in Validation allows you to get the matching information for an existing table field result that is changed by the Validation operator. In the following example the ButtonClicked event is used to start matching against the purchase order database.

Private Sub ValidationForm_ButtonClicked(ByVal ButtonName As String, ByVal pXDoc As CASCADELib.CscXDocument)
   Dim sPONumbers() As String
   ReDim sPONumbers(0)
   ' having multiple PONumbers in the table, extract these from the table and pass multiple numbers to the Match call
   sPONumbers(0) = pXDoc.Fields.ItemByName("PONumber").Text
   Select Case ButtonName
      Case "Button0"
         Match(pXDoc, "Base", "LIMLoc", "POLineItems", sPONumbers, "")
   End Select
End Sub

For documents that have table data available or when the table data was extracted by another locator, you can use the Match function (for example, within the Document_AfterExtract event) to match the existing table results against the purchase order database.

Private Sub Document_AfterExtract(ByVal pXDoc As CASCADELib.CscXDocument)
   ' get the PONumber and/or the VendorID from another field
   Dim sPONumbers() As String
   ReDim sPONumbers(0)

   sPONumbers(0) = pXDoc.Fields.ItemByName("PONumber").Text
   Dim sVendorID As String
   sVendorID = pXDoc.Fields.ItemByName("VendorID").Text
   If Len(sPONumbers)> 0 Or Len(sVendorID)> 0 Then
      Match(pXDoc, "Base", "LIMLoc", "POLineItems", sPONumbers, sVendorID)
   End If
End Sub

Your search for returned results.

Search tips

Match function