lookups

The lookups object is designed to run lookups to retrieve data from an external source, such as a SQL connection or an external API. When run, the lookup code should return a tab-separated-values list of data.

Lookup definitions are found in the im/lookups.ini and im/lookups.custom.ini files. Each lookup is in a section, headed by the name in brackets. Each section contains a description= line, and an optional parameters= list, a cols=list, and a value=name. The balance of the lookup section is code designed to set rows$ to a tab-separated-values list matching the columns named in the cols=list.

The cols=list value contains a comma-separated list of column headers that should align with the rows$ data returned by the lookup.

The value=name specifies which column has the actual data to be extracted when a user performs a lookup in the Image Manager.

Lookups can use parameters, passed into the running code as part of the name or as an array. Parameters can be passed to validations explicitly in an associative array param$[all] (i.e. p$["Val1"]="Value 1", passed as p$[all]), or via a syntax convention in the name (i.e. verifyitem(Val1="Value 1",Val2="Value 2") - note quotes are optional if commas are not in values). Parameters are very important when dealing with potentially large sets of data, using them as filters when requesting data from external sources. If a named value is passed both via parenthesized argument and parameter array, the parameter array value is used.

Lookups are used by "lookup" fields in job definitions. When a lookup is performed by the Image Manager, it displays the result in a grid. It uses the cols= list to create columns for the grid, and displays the rows returned by the lookup in cells of the grid. When the user selects a row, it uses the column specified in the value= definition line to determine what data to paste into the associated data field.

If a doc object is present, it is possible for a lookup run to update document properties and fields via that object.

errmsg$, lasterrmsg$ is set by validation code to indicate an invalid value

doc contains an inbounddoc object when the validation is run in the context of an image manager job, or a docflowdoc object when run from a docflow job. It can also contain a libdoc object if run from actions in the archive browser interface.

Run(name$,rows$[,param$[all]]) runs the lookup name$. It expects the lookup to create rows$ with tab-separated values that match the columns specified in the cols= line of the definition. Optionally pass a param$[all] associative array with parameter names as keys, or use the name syntax described above. It may set errmsg$ if an error occurs. The method returns true (1) if the errmsg$ variable is null.

Run$(name$[,param$[all]]) runs the lookup name$. It returns the value of rows$ created by the lookup's code, with tab-separated values that match the columns specified in the cols= line of the definition. Optionally pass a param$[all] associative array with parameter names as keys, or use the name syntax described above. It may set errmsg$ if an error occurs. The method returns true (1) if the errmsg$ variable is null.