Iconik DLR Lookup

Manual / Actions / Iconik

Find a Data Lookup Record and optionally copy its fields onto a target clip.

Read Shared action rules for disabling this action, outputs, error routing, and recovery. Configure the Iconik connection before using this action.

Configuration and behavior

This action finds exactly one Data Lookup Record in a selected Iconik collection tree. It can also copy fields from that record onto one target clip.

Ports: Found, No match, and Error. You must connect No match. A workflow with No match unconnected stays a draft and cannot be activated.

The form follows the order of the work: Find the DLR, then Update a clip, then, when that switch is on, Clip to update and Copy fields.

Update a clip off (lookup only). Relay finds the DLR and publishes its values. It reads no clip and writes no clip. Target clip stays empty. The Matched DLR values are the same as with the switch on. A Workflow Test of a lookup-only step writes nothing.

Update a clip on. Relay also validates the mappings, writes the clip, and reads it back. Success means every mapped field has the planned value.

Older saved steps. A step saved before this switch existed has no switch value. Relay runs it as if the switch is on when it names a target clip or holds at least one field mapping. The editor saves the switch value when you next open or save the step.

Example. A Watch Folder workflow extracts a game ID such as 4821 from the file name. DLR Lookup finds the game DLR with that ID and leaves Update a clip off. A later step uses the DLR date, opponent, and venue from Available data. Found continues the workflow. No match goes to a step you choose, for example a log message that names the game ID.

Which fields you can choose. Criteria and mappings follow different rules, and the editor offers only what a run accepts. A criterion can name any core asset field, including Asset ID and External ID, and any custom metadata field whose Iconik type Relay can match exactly. The picker prints the Iconik type beside each field, and these are the ones it offers: boolean, date, datetime, drop_down, email, float, integer, string, tag_cloud, text, and url. A custom field of any other type is not offered. DLR mappings read from and write to custom metadata only. No core asset field is offered as a mapping source or as a mapping destination, so DLR cannot write a core asset field.

A criterion saved on a field Iconik cannot match exactly is marked Unsearchable. A mapping saved on a core asset field is marked Core field. Relay never discards either one: the row keeps its value, the editor names the repair, and activation stays blocked until you fix it. A run stops before it sends one Iconik request, so the clip cannot change.

A criterion saved on a core asset field this Relay does not have is refused when the action runs: it takes Error with kind configuration before any Iconik request, so the clip cannot change. This can happen to a workflow saved by an older Relay whose list of core fields has since changed. Choose the criterion field again from the picker. Core field names are matched exactly, so a name in different letters, such as ID in place of id, is not the same field.

Each mapping has an empty-DLR policy, Leave unchanged or Clear, and a present-value policy: Overwrite, Write only if empty, Append for multiline text, Add to list for list fields, or Fail if not empty. New mappings default to Leave unchanged and Overwrite. The editor groups the action into stages: Find the DLR, Update a clip, Clip to update, and Copy fields. Each mapping is one row: the DLR field, an arrow, and the clip field. Open Rules on the row to change the two policies. When a mapping uses a policy other than the defaults, the button names it, for example Write only if empty. Source and destination types must be compatible, both must be single-value or both must be lists, and a read-only field cannot be a destination. One destination can appear only once. Append inserts one line break between existing and new text. Add to list keeps the existing order and adds only values the clip does not already hold.

Relay validates the target, criteria, saved field definitions, values, and complete mapping plan before the first write. One invalid mapping leaves the clip unchanged. It sends at most one custom-metadata update, then reads the clip back. Success means every mapped field has the planned value.

Checking the record Iconik returned. Before it reads or writes the clip, Relay checks the matched record against the search it sent. The record must sit in the selected DLR collection or anywhere below it, it must hold the value every criterion asked for, and it must carry a usable ID, a title, a status, and readable created and modified dates. The returned value must also be of the type the saved field declares: a criterion on a text field is not satisfied by a number with the same digits, a criterion on a number field is not satisfied by text, and a criterion on a true or false field is not satisfied by the word true. A date or a date and time the record spells another way still satisfies the criterion it matched, because Relay compares the moment and not the spelling. Relay never edits the text Iconik returned: a text criterion must match the returned value exactly, leading and trailing spaces included, and every value the lookup publishes carries the spacing the record really has. A value of nothing but spaces is no value at all, so a record whose title or status is only spaces is refused like one that has none. A criterion on a list field is satisfied when one returned member matches it exactly. A criterion on a single-value field must come back with exactly one value: a record that returns several values for a field saved as single-value contradicts its own field definition and is refused. The collections the record is in come from the search answer, which is why Relay does not read the record again. Each one must be a usable collection ID: a record that reports one Relay cannot read is refused before the clip is touched, and a collection reported twice is counted once, so Collection count is the number of different collections the record is in. Where those collections sit is not taken from the search answer at all: Relay reads the collections above them from Iconik itself, because a search answer that is out of date about where the record sits is out of date about the collections above it in the same breath. A record in the selected collection itself is in scope from the search answer alone and costs no extra requests. For a record in a subcollection, Relay reads the collections above it, one per level, and reports an error only when those reads show the record is outside your selected collection. A record can belong to several collections: Relay checks all of them and needs only one to prove the record is in scope, so an unrelated collection it could not read does not lose the lookup. A collection Relay could not read is reported as the read failure it is and never as a record out of scope, and it is reported only when no collection proved the record is in scope. A record that fails any of these takes Error as unavailable or incomplete_snapshot, and the clip is neither read nor changed. A matched record with no External ID is normal and publishes an empty value.

A collection tree more than 64 levels deep above the matched record is not walked, and one lookup resolves at most 256 collections in total however many collections the matched record reports. That total covers the whole lookup, including any attempt it makes after an interruption, so a lookup that is picked up again continues the same count rather than starting a new one. Relay stops with Error as unavailable rather than reading collections until the step runs out of time. Both limits are far above any real library, so only contradictory data reaches them.

No match. When the search completes and no DLR meets every criterion, the action leaves through No match. It is a normal result, not a failure. Relay reads and changes no clip. Matched DLR and Target clip stay empty, the outcome is no_match, and the match count is 0.

Multiple matches. More than one match takes Error with kind multiple_matches and the count in ${error.iconik.match_count}. Relay never chooses the first of several. Other Error kinds are configuration, permission, not_found, unavailable, partial_update, outcome_unknown, incomplete_snapshot, and transport. An unavailable target, invalid mapping, confirmed partial update, incomplete record, transport failure, or uncertain result also takes Error. A confirmed partial update leaves the applied values in place. A write whose response never arrives reports Outcome unknown, is not retried, and requires you to check the clip in Iconik.

A Workflow Test runs this action as part of the real workflow. With Update a clip on, it changes the target clip. With the switch off, it writes nothing. Values from a DLR appear in Available data after a Workflow Test runs the step. You are responsible for choosing a target and inputs whose changes are acceptable.

A lookup asks Iconik for the one matching record in a single search. It does not download the collection and does not get slower as the collection grows. Iconik reports how many records matched: none takes No match with a match_count of 0, more than one takes Error as multiple_matches carrying the true number, and exactly one supplies the matched record straight from the search. Relay does not read the matched record a second time. A search whose answer is missing or self-contradictory fails as unavailable before Relay reads or writes the target clip.

A run that finds the DLR publishes target_asset_id (empty when Update a clip is off), matched_asset_id, outcome, match_count, collection_id, collection, criteria, criteria_json, mapping_outcomes, written_values, and the matched record's own fields as asset_id, title, status, external_id, created_date, modified_date, and collection_count. The criteria_json, mapping_outcomes, and written_values outputs are JSON-bearing. After a recorded run, Available data offers their observed nested fields. written_values lists only the fields the action actually wrote, so its length is the real written count.

DLR Lookup also publishes a named result (Named Iconik values) in three groups that keep the source, the destination, and the mapping facts apart:

Only values the action verified appear under Confirmed written values, so a partial or unconfirmed write never reads as a confirmed one.

A DLR result recorded by an earlier Relay described extended asset details a DLR no longer returns. That older result stays readable in the job, so you keep your history: the editor shows its saved values and marks them as coming from an earlier version of the action. It cannot supply Available data and you cannot insert a reference to it. Run a new Test to select values from a DLR Lookup.

Testing a lookup. Use the workflow's Test, as for any other step. The Test runs the earlier steps first, so the lookup uses their values. With Update a clip on, a Test writes to the target clip. Turn the switch off to test only the lookup.