Existing Record Lookups

Existing Record Lookups run before a record is created in a connecting system. They let an endpoint check whether the record already exists — typically by an alternate identifier like email, employee number, or folder path — and decide what to do based on the answer.

For example, you might want to:

• Look the record up by email. If a single match is found, treat the save as an Update instead of a Create. Otherwise, create it.
• Look for an Egnyte folder by path. If the folder already exists, register the existing folder ID and skip the copy (and any child saves) so nothing gets duplicated.
• Chain two lookups: search by email first, then by phone number as a fallback, then create.

Lookups are configured per save action under the Existing Record Lookups tab on an endpoint's save configuration.

TIP

Lookups only run on Create. If the message already has a primary key for this connector and the engine would issue an Update, the chain is skipped.

Chain semantics

When a save fires, each lookup in the list runs in order. The engine sends the configured read request, counts the items returned, and applies the matching outcome rule.

For each lookup in the list:
  Run the read action
  Count the items in the response

  If 0 items   → apply "When None Found"
  If 1 item    → extract the matched key + flip to Update; stop the chain
  If > 1 items → apply "When Multiple Found"

The chain stops on the first terminal outcome (a match, a skip, or any error). If no lookup matches and every outcome says "continue chain," the save proceeds as a normal Create.

On a single match

When exactly one record matches (or one is selected via Use First / Use Last), the engine always:

1. Runs the configured Key Extraction Actions against the matched record to read its primary key.
2. Adds the key to the Model and emits it via key replication so future runs find the record via the normal index instead of repeating the lookup.
3. Flips WriteAction to Update. The configured Update URL / method / body fire against the existing record.

There is no per-lookup "skip on single match" option. That semantic is expressed at the endpoint config level — see Skip everything on match below.

Response handling

Each lookup has two independent settings that decide what happens when the match count isn't exactly one.

When None Found

Option	What it does
Continue Chain	Move on to the next lookup. If this is the last lookup, proceed to Create. (Default.)
Skip Save (no Create)	Stop the chain. The save will not run, and child saves are also skipped.
Error	Throw an error and fail the save. Useful when "no match" is unexpected.

When Multiple Found

Option	What it does
Error	Throw an error. (Default — safest choice.)
Continue Chain	Log a warning and move on to the next lookup.
Skip Save (no Create)	Stop the chain. The save will not run.
Use First Match	Pick the first item from the response. The engine then extracts its key and flips to Update (same as a normal single match).
Use Last Match	Same as Use First, but with the last item.

WARNING

Continue Chain on the last lookup proceeds as Create. If Continue Chain is selected and there are no more lookups in the chain, the save runs as a normal Create — even though multiple potential matches were just found upstream. This is rarely the intended behavior for multi-match; prefer Error or Skip Save unless you have a deliberate fallback lookup queued after this one.

WARNING

Every lookup requires at least one Key Extraction Action — the engine needs to know how to read the primary key from a matched record. The form surfaces a hint if you forget.

Skip everything on match: Create-only endpoints

If you want a single match to not fire the Update at all — recording the existing record's key but otherwise doing nothing — configure the endpoint as Create-only:

1. Open the endpoint configuration.
2. Under Supported Operations, set the value to Create only.
3. Save the endpoint.

Now when an Existing Record Lookup finds a match:

• The matched primary key is still extracted and registered for key replication.
• The runtime sees Supported Operations = Create and short-circuits before issuing the Update.
• The save is skipped (IsValidForSave = false), which also skips any child entity saves.

This is the canonical recipe for the "this record already exists in the destination, don't touch it" semantic (e.g. BHDP Egnyte folder subscribers). It's expressed at the endpoint level because that's where "this endpoint only writes new records" belongs conceptually — and it's consistent with how the bus filter already treats Create-only endpoints at message receipt.

Configuring a lookup

1. Select Build > Data Hubs from the main menu.

2. Select the appropriate Data Hub; then select an Endpoint to edit.

3. On the save action, open the Existing Record Lookups tab.

4. Select + to add a new lookup.

5. In the modal:

   • Response Handling: Pick the When None Found and When Multiple Found outcomes for this lookup.

   • Read Action: Fill in the request used to check for an existing record. For REST APIs this is the read URL and (optional) response selector; for SQL connectors it's the read command text; for delimited-file connectors it's the file location and name.

     TIP

     The read URL or body can use the same token replacements as save bodies, e.g. {PROP:Email}, {FK:SourceSystemKey}, {SYS:CurrentDateTime}. The engine resolves these against the Model before issuing the read.

   • Key Extraction Actions: Add at least one action telling the engine how to read the primary key out of the lookup response on a match.

6. Save the form. To add a chain, repeat steps 4–5 — each row in the table is a successive lookup.

Chained lookups

Order matters. The chain stops on the first terminal outcome. A typical "find by alternate ID" pattern looks like:

#	Read against	When None	When Multiple
1	/people?email={PROP:Email}	Continue Chain	Error
2	/people?phone={PROP:Phone}	Continue Chain	Error
3	/people?birthdate={PROP:Dob}	Continue Chain	Error

If all three return zero, the save proceeds as a Create. If lookup 2 finds exactly one record, the key is extracted, the save flips to Update, and lookup 3 never runs.

See Also

• Key Scraping — Configure ObtainPrimaryKeyAction; the same action type is used inside an Existing Record Lookup to extract the matched record's ID.
• Endpoint Configuration — Save action settings outside the lookup chain.
• Action Mapping — How save bodies and read URLs resolve {PROP:...} / {FK:...} / {SYS:...} tokens.