View source for Import Query Results (Import Provider)

<blockquote>{{#lst:Glossary|Import Query Results}}</blockquote>

== About ==

"Import Query Results" is one of the [[CMIS Import]] providers in Grooper. It is used to import files from '''CMIS Repositories''' for Batch processing in Grooper. It will import files from a folder structure of an on-premise or cloud-based document storage platform.
:*<li class="fyi-bullet"> While less common, Import Query Results can also import ''folders'' from CMIS Repositories. However, since importing files is most common, we focus on importing ''files'' in this article.


Just like any other Import Provider, Import Descendants is used to submit "'''Import Jobs'''". Import Jobs are how Grooper brings in files from a storage location for processing. For example, it's how PDFs from a Windows folder get into Grooper or messages from an email inbox get into Grooper. When an Import Job runs, Grooper first creates a Batch and then creates a Batch Folder for each imported file. A copy of the file is attached to the Batch Folder. This becomes the Batch Folder's "attachment" and is used when applying activities like "Split Pages".
:*<li class="fyi-bullet"> When files are imported into Grooper, a link to that file is stored on the Batch Folder. This link maintains a connection between the file's source location and the document in Grooper. This link also makes "Sparse" imports possible. [[#Import Mode (and "Sparse" imports)|See below for more.]]


Import Jobs are submitted in one of two ways:
* '''By a user from the Imports page''': Ad-hoc or "user directed" Import Jobs are submitted from the [[Imports Page]], using the "Submit Import Job" button.
* '''From an Import Watcher service''': Automated or "scheduled" Import Jobs are submitted by an '''[[Import Watcher]]''' service according to its Poling Loop or Specific Times specification.
In both cases, an "Import Descendants" can be selected and configured using using the "Provider" property.

{{#lst:CMIS Import|import_query_results_and_descendants_similarities}}

== Prereqs: CMIS Repository ==

A CMIS Repository allows Grooper access to files and folders within a storage platform.

Because Import Query Results imports from a CMIS Repository, you can import from numerous storage platforms determined by the "CMIS Binding" used. These CMIS Bindings include:
* [[NTFS]] to connect to Windows folders
* [[FTP]] to connect to FTP directories
* [[SFTP]] to connect to SFTP directories
* [[Exchange]] to connect to Outlook inboxes
* [[SharePoint]] to connect to SharePoint sites (and document libraries)
* [[OneDrive]] to connect to OneDrive drives
* [[Box]] to connect to Box accounts
* [[AppXtender]] to connect to AppEnhancer applications

Before you can import files from these platforms using Import Query Results, there's some setup required in the Grooper Design page. You must:
# Create and configure a CMIS Connection.
# Import a folder location as a CMIS Repository.

This will allow you to import files from folders accessed by the CMIS Repository. For information on CMIS Connections and CMIS Repositories, including how to create them in Grooper, visit the [[CMIS Connection]] page.

[https://app.supademo.com/demo/cm8ddjcr91rb92ugqp7k9phqo Click here for an interactive walkthrough.]

== Example Import Query Results configuration ==

Import Query Results relies on a "CMIS Query" to import files from a CMIS Repository. The CMIS Query (aka CMISQL Query) uses a syntax structure similar to a SQL query. Instead of querying rows in a database based on column values, you're querying documents in a storage location based on file property and metadata values.
* The general CMIS Query format is: <code>'''SELECT * FROM''' ''<a type of document in the CMIS Repository>'' '''WHERE''' ''<according to certain search conditions>''</code>
* What "type of document" in can search for in the FROM clause is determined by the storage platform and the CMIS Binding.
** Example: For the NTFS binding you select "<code>FROM File</code>" for files in a Windows folder.
** Example: For the Exchange binding you select "<code>FROM Message</code>" to search for email messages.
* In the <code>WHERE</code> clause, you can set search parameters based on file properties and metadata values called "CMIS properties". What CMIS properties are "queryable" will also depend on the the CMIS Repository and its CMIS Binding.
** Example: The Exchange binding has a queryable "Subject" property.
** Example: Fields in a Box metadata template are queryable for the Box binding.
**<li class="fyi-bullet">Which CMIS properties are queryable can be determined by (1) navigating to the CMIS Repository in the Grooper node tree (2) going to the "Types" tab (3) selecting the CMIS document type whose properties you want to inspect and (4) reviewing the "Queryable" column for each CMIS property.
* The <code>WHERE</code> clause is also used to set the folder scope, using the <code>IN_FOLDER</code> and <code>IN_TREE</code> predicates (where supported).
* More information on CMIS Queries (including unsupported query configurations for various CMIS Bindings) can be found in the [[CMIS Query]] article.

<big>Example: Submitting Import Query Results from the Imports Page</big>

[https://app.supademo.com/demo/cm8ergggh03ij12zdakzyt3jp Click here for a step by step walkthrough.]

# Go to the Imports Page.
# Press the "New Import Job" button.
# This brings up the "Submit Import Job" editor.
# Enter a description in the Description property (This is required).
# Open the "Provider" dropdown (Press the "☰" button).
# Select "Import Query Results" from the dropdown list.
# Expand the Provider settings to configure it.
# Open the "Repository" node selector (Press the "☰" button).
# Select the CMIS Repository you wish to import from.
# Open the "CMIS Query" editor (Press the "..." button).
# Enter the CMIS Query by either:
#* Typing it into the Query Editor.
#* Or, using the Query Editor's property grid to construct the query (The text will populate the Query Editor as you configure these properties).
#**<li class="fyi-bullet"> A more in depth explanation of the Query Editor and CMIS Queries can be found in the [[CMIS Query]] article.
# Configure the Import Mode property, as needed.
# Configure the Batch Creation settings, as needed.
# Configure the file disposition options (Delete Item, Move To Folder, or Update Properties), as needed.
# Configure any remaining Import Descendants properties, as needed.
# Press the "Submit" button when finished.
# Your Import Watcher service will pick up and execute the Import Job.