Resolve reference
The service task "Resolve reference" searches for the record of a data schema that matches a free text, such as the supplier name read from an invoice, and returns its id. This turns text coming from documents or emails into a reference to an existing record. One column of the schema is compared in six stages, from exact match to similarity search.
Technical name prio_resolveReference · Category in the "Select service task" dialog: Data & References
When is this service used?
- Assigning incoming invoices: The supplier name from the PDF analysis is matched to the supplier record of Musterfirma GmbH before the invoice is saved.
- Delivery notes to customers: The sender of a delivery note is looked up in the "Customers" schema.
- Requests from forms: A company entered as text in a public form is matched against the customer base.
Prerequisites
The data schema has to be available for SQL queries, as used by the SQL-filtered reference field. Every search is a query on this database; it takes a few seconds and incurs costs per query.
Input
| Field | Type | Required | Meaning |
|---|---|---|---|
dataSchemaId |
string | yes | Id of the data schema, e.g. customers or contacts/organisation. The search uses the last path segment, including the schemas derived from it |
searchValue |
string | yes | The search text; empty or whitespace only aborts |
attributeName |
string | no | Column to compare. Default document_name (the document name of the record). Allowed are letters, digits and underscore, starting with a letter or underscore |
{
"dataSchemaId": "suppliers",
"searchValue": invoice.supplierName,
"attributeName": "document_name"
}
The search runs in two steps. First, candidates are pre-filtered: every word of the search text with at least three characters has to occur in the column (case-insensitive). Then the candidates are compared in this order; the first stage with a hit wins:
| Stage | matchType |
Meaning | score |
|---|---|---|---|
| 1 | exact |
column equals the search text | 1 |
| 2 | contains |
column contains the search text | 1 |
| 3 | reverseContains |
search text contains the column | 1 |
| 4 | tokenMatch |
all words of the search text occur; punctuation is ignored | 1 |
| 5 | startsWith |
column starts with the search text | 0.9 |
| 6 | fuzzy |
similarity (Jaro-Winkler) at least 0.80 | similarity, rounded |
If several records match in the same stage, the shortest value wins; for reverseContains the longest.
Output
{
"found": true,
"dataObjectId": "01JCX4R9M2T7V8W3Y5Z6A7B8C9",
"documentName": "Huber Elektrotechnik GmbH & Co. KG",
"dataSchemaId": "suppliers",
"matchType": "tokenMatch",
"score": 1
}
found:trueif a record was found. Without a hit,{ "found": false, "dataObjectId": null, "documentName": null, "matchType": null, "score": 0 }is returned and the process continues.dataObjectId: Id of the record found, usable as the value of a reference field.dataSchemaId: Schema of the hit. With derived schemas it may differ from the input value.
The result is stored under the result path, e.g. supplier.
Errors and behavior
- Input errors throw:
prio_resolveReference: dataSchemaId is required,prio_resolveReference: searchValue is required,prio_resolveReference: invalid attributeName "…". - Database errors (table missing, unknown column, query fails) throw as well. With an error boundary event the process continues there; without one the instance ends in error with a resume point and an error email to the process owner.
- No hit is not an error:
foundisfalse, the process continues. - Retries: Up to three attempts only for transient errors (timeout, service briefly unavailable). Time limit 900 seconds. The service only reads and does not change any data.
- The dry run does not execute a query; the step returns a sample output from the catalog.
Example
Musterfirma GmbH reads incoming invoices with AI: Extract data. The message contains invoice.supplierName = Huber Elektrotechnik GmbH & Co KG; in the "Suppliers" schema the record is called "Huber Elektrotechnik GmbH & Co. KG".
- Input expression as above, result path
supplier. - Output:
found: true,matchType: "tokenMatch",score: 1. The missing dot in "Co KG" does not matter because punctuation is removed when the words are compared. - Gateway:
supplier.found and supplier.score >= 0.9→ a database step saves the invoice withsupplier.dataObjectIdin the reference field; otherwise the user task "Assign supplier".
Frequently asked questions
Can several columns be searched at once?
No, exactly one column (attributeName) is compared. For a second column the service is called a second time.
\"Müller GmbH\" does not find \"Mueller GmbH\".
Umlauts are kept and are not transliterated to ae, oe, ue. Whether the similarity search still applies depends on the rest of the name; matchType shows it.
Should dataObjectId be saved without checking?
Better not. From stage 5 on (startsWith, fuzzy) wrong assignments are possible. Check found, matchType and score in a gateway and present uncertain hits to a user task.
The search is slow although the schema is small.
Every search is a database query that takes a few seconds. If the search text consists only of short words (under three characters, e.g. "AG"), the whole table is read, which takes additional time.
Next step
Database: how references between records are built and where the id of a record is found.