XML Lookup (Lookup Specification)

XML Lookup is a Lookup Specification that performs a lookup against an XML file stored as a draft Resource File in the package_2 Project. XML Lookups use XPath expressions to select XML nodes and map XML attributes or an XML element's text to Grooper fields.

About

XML Lookup was designed to be a sort of middle-ground between Grooper's Lexicon Lookups and Database Lookup. Lexicon Lookup and Database Lookups have their own pros and cons.

Lexicon Lookup

• Pro: Portability - Lexicon Lookups use a Grooper Lexicon to perform a lookup operation. Lexicons can be easily shared between Grooper users (or since a Lexicon is essentially just a text-based list, their text can be easily copied and pasted).
• Pro: Handle simple data relationships well - Lexicon Lookups are the simplest lookup type. They are essentially key-value lists where the lookup field is the key and the target fields are parsed from comma separated values.
• Con: Handle complex data relationships poorly - Because they are so simple, they cannot begin to express complex data structures like a relational database can.

Database Lookup

• Pro: Handle both simple and complex data relationships well - Database are effective at describing simple data relationships, such as simple key-value pairs but excel at organizing complex data structures.
• Con: Portability - Databases require at least some hardware and software infrastructure to support them. Sharing them from one environment to another is not always easy (certainly not as easy as passing a file around).

Thus, the XML Lookup was born. XML can describe more complex data relationships than a Grooper Lexicon through XML node hierarchy and attributes. But, an XML file is just as portable as a Lexicon (if not more so). If you have a fairly complex (but also static) data structure you want to use to perform a lookup, consider using XML Lookup.

The general setup

1. Import the XML file into a Grooper Project by dragging it onto the Project (or a folder in the Project). This will create a Resource File for the XML file.
2. Add a XML Lookup to Data Model (or Data Section or Data Table if appropriate)
3. Point to the XML file by configuring the XML Lookup's "Source" property.
4. Configure the XML Lookup's "Record Selector".
   • This uses an XPath expression to select the XML nodes (records) you want to retrieve.
   • Use the % character to insert field variables in your XPath expression (e.g. %GrooperFieldName).
   • These are the "lookup fields" for XML Lookup. This will insert insert values from Grooper fields into the XPath expression at runtime.
   • Example: /Root/Record[xmlElement='%GrooperFieldName']
5. Configure the XML Lookup's "Value Selectors".
   • This is how you map data in the XML file to Grooper fields (XML Lookup's "target fields").
   • One or more Value Selector may be added.
   • Each Value Selector specifies an XPath expression and maps the result to a Grooper field.
     • The Value Selector XPath is relative to the record node returned by the Record Selector. The path should start at the root of the record not the root of the XML itself.
6. Extract. The XML Lookup executes as follows:
   1. The Data Model executes its Data Field/Data Section/Data Table extractors.
   2. XML Lookup loads the "Source" XML file.
   3. The Record Selector XPath is evaluated (with lookup variables replaced by field values). The lookup will either:
      • Hit - If the XPath selects exactly one record node, this results in a successful lookup.
      • Miss - If your XPath does not return any nodes, no data will be populated and the "Miss Disposition" will determine what happens next.
      • Conflict - If multiple record nodes are returned, the "Conflict Disposition" will determine how multiple results are handled.
   4. For successful lookups, the Value Selectors evaluate their XPath relative to the record node and populate the corresponding Grooper fields.