> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Lookup

> Retrieve values from Square and insert them into an Arc message in the flow.

export const DbasaLookupTestLookup = ({datasource = "the data source"}) => <p>
    Use the <strong>Test Lookup</strong> button to check your configuration and see the result
    without having to process files manually. Use the <strong>Save Sample Data</strong> button to
    save the output as a sample for mapping later in the flow.
  </p>;

export const DbasaLookupAdvanced = ({datasource = "the data source"}) => <>
    <img src="/public/images/dbsa_lookup_advanced.png" alt="Lookup advanced settings" width="600" />
    <ol>
      <li>Use <strong>No Matching Record Found Action</strong> to specify what should happen if no record is found that matches the query.</li>
      <li>
        The {datasource} connector can perform Lookup queries against a local cache instead of
        querying {datasource} directly for each Lookup. This can improve query performance,
        especially with larger databases. To enable this, check <strong>Enable cache</strong> and
        configure the rest of the fields.
        <ul>
          <li><strong>Cache Tolerance</strong>: Controls how often the connector issues a query to the data source to refresh the cache.</li>
          <li><strong>Cache Tolerance Unit</strong>: The <strong>Cache Tolerance</strong> unit. Choose Minute, Hour, or Day.</li>
          <li><strong>Cache Provider</strong>: Choose which driver to use to facilitate the connection to the cache database.</li>
          <li><strong>Connection String</strong>: When set, the connector uses the database specified here for caching.</li>
        </ul>
      </li>
    </ol>
    <Note>
      <ul>
        <li>If a query returns no results from the cache, the connector queries {datasource} directly.</li>
        <li>If your query statement contains a <code>limit</code>, <code>offset</code>, or <code>groupby</code> parameter, the cache function does not work. These queries go directly to {datasource}.</li>
      </ul>
    </Note>
  </>;

export const DbasaLookupQueryMode = ({datasource = "the data source"}) => <>
    <p>Follow the steps below to use the Query mode to configure a Lookup action for the {datasource} connector.</p>

    <img src="/public/images/dbsa_lookup_query.png" alt="Lookup query mode" width="600" />

    <ol>
      <li>
        <strong>Output Destination</strong>: select <strong>XPath</strong> to insert the query response values into an XML file or <strong>Header</strong> to insert the query response value into a message header.
        <ul>
          <li>XPath: When you choose XPath, the destination is in two parts. The <strong>Parent-Level XPath</strong> should already exist in the XML document. The <strong>New Node Name</strong> is the name of the node that is injected into the XML document to hold the result of the lookup. Each column in the query has its own XML element (leaf level) in the XML element provided here.</li>
          <li>Header: When you choose Header, the connector adds one header to the output message for each column in the query. The values are comma-separated for each record that is returned from the database.</li>
        </ul>
      </li>
      <li>In <strong>Query</strong>, enter the SQL query to retrieve data from {datasource} tables.
        <ul>
          <li>XPath: Format the path as <code>{'${XPATH:/path/to/element}'}</code>. For example, <code>{'SELECT CustomerID FROM Customers WHERE CustomerName = ${XPATH:/Items/Invoices/Customer}'}</code>.</li>
          <li>Header: Format the path as <code>{'${HEADER:HeaderName}'}</code>.</li>
        </ul>
      </li>
      <li>The two checkboxes let you configure what should happen when the query returns multiple results.
        <ul>
          <li>Check <strong>Use First Result</strong> to always use the first result.</li>
          <li>Check <strong>Error if multiple results</strong> to see an error when multiple results are returned.</li>
        </ul>
      </li>
    </ol>
  </>;

export const DbasaLookupFilters = () => <>
    <p>
      You can build complex filters by defining individual filters and/or groups of filters. For
      readability, expand the <strong>Filters</strong> section by clicking the expander icon <img src="/public/images/validate_expander.png" alt="expander" noZoom style={{
  display: "inline-block",
  verticalAlign: "middle",
  height: "0.9em",
  margin: 0
}} /> on the
      right side of the bar.
    </p>
    <p>To add a filter, click <strong>Add Filter</strong> or <strong>Add Group</strong>.</p>
    <p>
      When you build your filters, use the dropdowns to make your selections and choose your
      operator. Then specify the value to filter by. You can choose from the following:
    </p>
    <ul>
      <li>Message Header</li>
      <li>Input XML</li>
      <li>Static Value</li>
    </ul>
    <p>
      When you select Input XML for a filter, if you have uploaded a sample file, the editor displays
      a tree representation of the document so you can easily find the XPath you need, as shown in
      the image below.
    </p>
    <img src="/public/images/dbsa_lookup_filter.png" alt="Lookup filter configuration" width="800" />
    <p>You can reorder filters and groups. Click the handle <img src="/public/images/xmlmap_condition_handle.png" alt="handle" noZoom style={{
  display: "inline-block",
  verticalAlign: "middle",
  height: "0.9em",
  margin: 0
}} /> and drag the object to a new location.</p>
  </>;

export const DbasaLookupDesignerMode = ({datasource = "the data source"}) => <>
    <p>Follow the steps below to use the Designer to configure a Lookup action for the {datasource} connector.</p>

    <img src="/public/images/dbsa_lookup_designer.png" alt="Lookup designer" width="600" />

    <ol>
      <li>Use the <strong>Table</strong> drop-down to select the table to include.</li>
      <li>Choose the set of <strong>Columns</strong> that you want to include from the table.</li>
      <li>
        <strong>Output Destination</strong>: select <strong>XPath</strong> to insert the query response values into an XML file or <strong>Header</strong> to insert the query response value into a message header.
        <ul>
          <li>XPath: When you choose XPath, the destination is in two parts. The <strong>Parent-Level XPath</strong> should already exist in the XML document. The <strong>New Node Name</strong> is the name of the node that is injected into the XML document to hold the result of the lookup. Each column in the query has its own XML element (leaf level) in the XML element provided here.</li>
          <li>Header: When you choose Header, the connector adds one header to the output message for each column in the query. The values are comma-separated for each record that is returned from the database.</li>
        </ul>
      </li>
      <li>Use <strong>Record Limit</strong> to specify what should happen when the query returns multiple results.
        <ul>
          <li>If you choose <strong>Use First Result</strong> from the dropdown, you can use the <strong>Error if multiple results</strong> to see an error when multiple results are returned.</li>
          <li>If you choose <strong>Custom Limit</strong>, you must specify the limit in the field that appears.</li>
        </ul>
      </li>
      <li>Use <strong>Order by</strong> to choose which column to order the results by.</li>
      <li>The <a href="#filters">Filters</a> section lets you create filters to build the query WHERE clause, including references to headers or XML from the input file.</li>
    </ol>
  </>;

export const DbasaLookupConfiguration = () => <p>
    Use this section to define the table and columns to include in your query.{' '}
    <a href="#designer-mode">Designer Mode</a> helps you pick the table and columns you want to
    target with your query, instead of requiring you to build the query free form. However, you can
    use <a href="#query-mode">Query Mode</a> if you prefer to write your query from scratch.
  </p>;

export const DbasaLookupIntro = ({datasource = "the data source", siteName = "CData Arc", siteNameShort = "Arc"}) => <>
    <p>
      The Lookup action retrieves values from {datasource} and inserts those values into an existing
      Arc message in the flow.
    </p>
    <ol>
      <li>In the {siteName} flow, drag an arrow from the connector that will provide input to the {datasource} connector.</li>
      <li>Optionally, choose a <strong>Sample File</strong>. A sample file is recommended because it allows the connector to provide more context about the file structure and helps you build <a href="#filters">filter</a> conditions.</li>
      <li>Once you have completed the configuration steps below, in the {siteNameShort} flow, drag an arrow from the {datasource} connector to the connector where you want your resulting XML or Header data to go.</li>
    </ol>
  </>;

<DbasaLookupIntro datasource="Square" />

## Lookup Configuration

<DbasaLookupConfiguration />

### Designer Mode

<DbasaLookupDesignerMode datasource="Square" />

### Filters

<DbasaLookupFilters />

### Query Mode

<DbasaLookupQueryMode datasource="Square" />

## Advanced

<DbasaLookupAdvanced datasource="Square" />

## Test Lookup

<DbasaLookupTestLookup datasource="Square" />